共通規約

AGTCloud APIに共通するEndpoint、アドレス、認証、Content-Type、レスポンス処理、エラー復旧のルールを説明します。

このページでは、AGTCloud APIのEndpointに共通する呼び出し規約を説明します。Endpoint固有のフィールド、状態、レスポンス構造については、対応するAPI Referenceページを参照してください。

APIアドレスとBase URL

このページで使用するAPIアドレスはhttps://api.agtcloud.cnです。OpenAI互換SDKでは、https://api.agtcloud.cn/v1をBase URLとして使用します。

用途	アドレスの構成	例
Raw HTTPリクエスト	APIアドレス + Endpointの完全なPath	`https://api.agtcloud.cn` + `/v1/chat/completions`
OpenAI互換SDK	Base URL + SDKメソッドが生成するPath	`https://api.agtcloud.cn/v1`
Realtime WebSocket	WebSocketアドレス + 接続Path	`wss://api.agtcloud.cn/v1/realtime?model=MODEL_ID`

/v1を重複して追加しないでください

https://api.agtcloud.cn/v1にはすでに/v1が含まれています。互換SDKを使用する場合は、SDKメソッドが生成するPathに/v1を追加しないでください。追加すると、リクエストが/v1/v1/...へ送信される可能性があります。

認証

保護されたAPIの多くはBearer API Keyを使用します。

Authorization: Bearer your-api-key

Anthropic Messagesは専用の認証HeaderとAPIバージョンを使用します。

x-api-key: your-api-key
anthropic-version: 2023-06-01

anthropic-betaなどの任意Headerや、その他のプロトコルに必要な認証方式は、対応するEndpointページを参照してください。

KeyはAPI Keysで作成、管理します。リクエストにはAPI Keyのみを送信し、コンソールのパスワード、Cookie、管理者Token、アップストリームプロバイダーのKeyを使用しないでください。

以下は最小限のChat Completionsリクエストです。

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  --request POST \
  --header 'Authorization: Bearer your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "こんにちは"
      }
    ]
  }'

API Keyの作成、ローテーション、本番環境での安全な保存方法については、APIキーと認証を参照してください。

リクエストパラメーターの配置

Endpointページでは、リクエスト内の位置ごとにパラメーターを分類しています。

パラメーターの位置	用途	例
Path Parameters	特定のリソースやタスクを識別する	`/v1/videos/{video_id}`
Query Parameters	フィルタリング、バリエーション、出力を制御する	`?variant=video`
Headers	認証情報やコンテンツネゴシエーション情報を送信する	`Authorization`、`x-api-key`、`Content-Type`
Request Body	モデル、入力、生成パラメーターを送信する	JSONまたはMultipartフォーム

Path Parameterは送信前にURLエンコードしてください。未使用の任意パラメーターには空文字列を設定せず、省略してください。

Content-Typeとデータ形式

データ形式	主なContent-Type	処理方法
JSONリクエストとレスポンス	`application/json`	リクエストオブジェクトをシリアライズし、JSONを解析する
ファイルとフォームのアップロード	`multipart/form-data`	HTTPクライアントにMultipart boundaryを生成させる
SSEストリーム	`text/event-stream`	イベント境界に沿ってデータを継続的に読み取る
SDP	`application/sdp`	一部のRealtime接続ネゴシエーションで使用する
バイナリファイル	`video/mp4`、音声メディアタイプなど	バイトストリームを読み取り、保存または転送する

Multipartのboundaryをハードコードしないでください。ブラウザー、SDK、HTTPクライアントにフォームデータから完全なContent-Typeを生成させてください。

モデルID

Referenceの例にあるMODEL_IDはプレースホルダーです。現在のAPI Keyで利用できるモデルIDに置き換えてください。モデルカタログでモデルを確認するか、Try ItにKeyを入力して、そのKeyで利用できるモデルを取得できます。

モデル、プロトコル、アップストリームプロバイダーは別の概念です。

モデルIDは対象モデルを選択します。
Endpointはクライアントが使用するプロトコルとメッセージ構造を決定します。
1つのモデルが複数のプロトコルEndpointで利用できる場合も、一部のフィールドにのみ対応する場合もあります。

レスポンスの解析

レスポンスは次の順序で処理してください。

HTTPステータスを確認する

成功オブジェクトとエラーのどちらを解析するか決める前に、リクエストの成否を確認します。レスポンス本文の単一フィールドだけで成功を判断しないでください。

Content-Typeを確認する

実際のメディアタイプに応じて、JSON、SSE、テキスト、バイナリのParserを選択します。ダウンロードEndpointをJSON Parserで強制的に処理しないでください。

現在のプロトコルのフィールドを読み取る

Chatは一般にchoicesを返しますが、Responses、Gemini、非同期タスク、WebSocket APIは異なる構造を使用します。すべてのAPIが同じレスポンスオブジェクトを返すと想定しないでください。

追跡情報を保存する

リクエスト時刻、Method、Path、モデル、HTTPステータスを保存します。レスポンスにRequest IDが含まれる場合は併せて保存しますが、完全なAPI Keyや機密性の高い入力をログへ記録しないでください。

ストリーミングレスポンス

SSE APIは、1つのHTTPレスポンスで複数のイベントまたはデータチャンクを送信します。接続が閉じるまで待ってレスポンス全体を1つのJSONとして解析せず、データを段階的に読み取ってください。

Endpointに記載された終了イベントまたはマーカーを識別します。
コンテンツの差分、ツール呼び出し、使用量、エラーイベントを個別に処理します。
ネットワーク接続が中断した場合、それまでに受信した内容を完全な結果として扱わないでください。
ストリーミングイベントの構造はプロトコルごとに異なります。現在のEndpointに対応するイベント定義を使用してください。

非同期タスク

動画、MidjourneyなどのAPIは、通常は最初にタスクIDを返し、その後で取得Endpointから進捗と最終結果を提供します。

タスクを送信 → タスクIDを保存 → ステータスを取得 → 終了状態を判定 → 結果を読み取る

タスクIDのフィールド名、ステータス値、取得Pathはプロトコルごとに異なります。id、task_id、video_id、各プロトコルのステータス値を混在させないでください。

ポーリングには間隔と全体のタイムアウトを設定し、タスクが成功、失敗、キャンセルのいずれかになった時点で停止してください。送信リクエストがタイムアウトしてもタスクが作成された可能性がある場合は、新しい課金対象タスクを作成する前に元の状態を確認してください。

HTTPステータスと再試行

以下は一般的な処理指針です。具体的なエラー構造は、実際のEndpointレスポンスを参照してください。

HTTPステータス	一般的な意味	推奨対応
`400`	リクエスト形式、フィールド、フィールドの組み合わせが無効	リクエストを修正してから再送信する
`401`	API Keyがない、無効、または認証Headerの形式が不正	認証情報とKeyの状態を確認する
`403`	現在のアカウント、Key、リソースに対する権限が不足	APIアドレス、権限、アカウント状態を確認する
`404`	Path、モデル、タスク、リソースが存在しない	URL、モデルID、リソースIDを確認する
`429`	レート、同時実行数、利用可能なクォータの制限に達した	レスポンスの指示に従って待機し、再試行回数を制限する
`5xx`	プラットフォームまたはアップストリームサービスの一時的なエラー	バックオフを使用して再試行回数を制限する

すべてのエラーを無期限に再試行しないでください。パラメーター、認証、権限のエラーは、問題を修正した後にのみ再送信してください。タスク作成など副作用を伴うリクエストを再試行する前に、すでに受理されていないか確認してください。

完全な診断手順は、エラーとトラブルシューティングを参照してください。

使用量、時刻、拡張フィールド

使用量データの有無やフィールド名は、プロトコルとモデルによって異なります。クライアントは、使用量データが省略またはnullになる場合に対応してください。
時刻フィールドにはUnix秒、Unixミリ秒、文字列のタイムスタンプが使用される場合があります。EndpointのSchemaに従って解析してください。
プロバイダーの拡張フィールドは通常、一部のモデルにのみ適用されます。すべてのモデルに共通する機能として扱わないでください。
互換プラットフォームの拡張によってレスポンス全体の解析が失敗しないよう、重要でない未知のフィールドを許容してください。

セキュリティとログ

長期間使用するAPI Keyは、信頼できるサーバーまたはシークレット管理サービスに保存してください。本番のWeb、デスクトップ、モバイルクライアントへ埋め込まないでください。
ドキュメントのTry Itは、ユーザーがブラウザーから行う一時的なテスト専用です。共有デバイスでは長期間有効な本番用Keyを使用しないでください。
Keyを公開リポジトリ、スクリーンショット、ログ、サポートチケットに含めないでください。
トラブルシューティング資料から、Prompt、ファイルURL、アカウントデータ、機密性の高いリクエストまたはレスポンス内容を削除してください。
使用しなくなった、または漏えいした可能性があるKeyを無効化または削除し、そのKeyを使用するすべてのサービスを更新してください。

続けて読む：APIリファレンス · クイックスタート · エラーとトラブルシューティング

このページの内容