認証と基本仕様

このページはすべてのエンドポイントに共通する取り決めをまとめたものです。ベースアドレス、認証、リクエストとレスポンスの形式、ページネーション、レート制限、冪等性、エラー処理を含みます。個別エンドポイントのパラメータと例はエンドポイント概要および各エンドポイントのページを参照してください。

ベースアドレス

認証

すべてのエンドポイントが同じプラットフォーム API Key を使用します：

Authorization: Bearer sk-你的APIKey
Content-Type: application/json

Bearer プレフィックスは省略できる（ただし推奨しない）

実測した 4 通りの書き方：

プラットフォームは生の token も受け付けるため、200 が返ることはクライアントの設定が正しいことを意味しません。逆に、あるクライアントが 401 を返す場合は、Key 自体を疑う前に、まず Authorization ヘッダー全体を送信し忘れていないかを確認してください。常に Bearer 形式を使用してください。

API Key が欠落している、誤っている、無効化されている、または現在のアカウントに属していない場合は HTTP 401 を返します：

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)",
    "type": "new_api_error"
  }
}

code が空文字列であることに注意してください。 認証失敗時にプラットフォームは code を埋めないため、code が空かどうかで リクエストがエラーかどうかを判断しないでください。HTTP ステータスコードを基準にしてください。message 内の request id はそのまま取り出してチケット起票に利用できます。

この種の認証失敗はすべてのエンドポイントで構造が同一で、message にリクエスト識別子が付くため、調査が容易です。

レスポンス構造

プラットフォームには 3 種類のレスポンス構造があり、クライアントは HTTP ステータスコードとレスポンスボディの両方を確認する必要があります。

モデル、テキスト、画像、動画、音声のエンドポイント

成功時は結果オブジェクトを直接返し、失敗時は HTTP が 2xx 以外で error オブジェクトを伴って返します：

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

動画タスクの照会は例外です。タスクが見つからない場合は 400 を返し、レスポンスボディはトップレベルの { code, message, data } 構造（code は文字列 task_not_exist）であり、前述の error オブジェクトではありません。 詳細はエラーコードとトラブルシューティングを参照してください。 code、type、param の値はエラーの種類によって変わるため、調査時は message を主とし、固定の code テキストだけに照合しないでください。

素材ライブラリのエンドポイント

成功時も失敗時も統一構造を使用します：

{ "code": 0, "data": {}, "msg": "OK" }

{ "code": 401, "data": null, "msg": "API Key 无效或已失效" }

失敗時の HTTP ステータスコードは code と一致します（400 / 401 / 404 / 429 / 502 / 503）。素材の審査が未完了であることはエラーではなく、200 レスポンスの status フィールド（Processing / Active / Failed）です。

ページネーション

素材グループ、素材一覧などのリスト系エンドポイントは統一のページネーションパラメータを使用します：

レスポンスの data.total は総件数、data.page、data.page_size は今回有効なページネーションパラメータです。次のページがあるかどうかは必ず total を読んで判断し、「今回返された件数」で判断しないでください。

レート制限とリトライ

429 と一時的な 5xx のみリトライしてください。400、401、403、404、409 はリクエストまたは権限の問題であり、リトライしても成功しません。

冪等性と重複送信

プラットフォームはエンドポイントをまたぐ自動の冪等キーを提供しません。業務側で 1 回だけ送信されるようにしてください：

• ユーザー操作ごとに、まず自社データベースへ業務レコードを 1 件記録してからプラットフォームのエンドポイントを呼び出してください。
• 動画タスクと素材の送信では、いずれもプラットフォームが返す ID を保存し、リトライ前に作成済みかどうかを照会してください。
• 素材が Processing の間は重複して送信しないでください。そうしないと複数の素材が作成されます。
• 課金は実際に送信が成功したタスクに基づきます。重複送信は二重課金の原因になります。

推奨される呼び出し順序

GET  /v1/models                     选择模型，确认能力与可用性
POST /api/v1/materials/groups       需要素材时创建分组
POST /api/v1/materials/assets       提交图片，保存 asset_id
GET  /api/v1/materials/assets/{id}  轮询到 status 为 Active
POST /v1/video/generations          提交视频任务，用 asset://<id> 引用素材
GET  /v1/video/generations/{id}     轮询任务，读取结果或错误

サーバー側での実装の推奨事項

1. リクエストごとに適切なタイムアウトを設定し、「タイムアウト」と「ユーザーによるキャンセル」を区別する。
2. 429 と一時的な 5xx には有限回のバックオフリトライを行い、その他のエラーはそのまま呼び出し元に返す。
3. 業務リクエスト番号、モデル ID、素材 ID、タスク ID、プラットフォームが返すリクエスト識別子を保存し、調査に備える。
4. API Key をログ、エラー通知、フロントエンドの計測、スクリーンショットに書き込まない。
5. 大きなファイルはオブジェクトストレージの公開 HTTPS アドレスまたは素材ライブラリの asset:// 参照を優先し、リクエストボディに詰め込まない。

次のステップ