エラー、制限、利用状況
エラー形式
エラーボディの形式は、APIプロトコルとエラーが発生する段階によって異なります。
- OpenAI互換API:
{"error": {"type": "...", "message": "..."}}。一部のエラーにはcodeが含まれます。 - Anthropic互換API:
{"type": "error", "error": {"type": "...", "message": "..."}}。 - APIキーおよび課金チェック（リクエストがモデルに到達する前）:
{"code": "...", "message": "..."}。
トラブルシューティングの際は、まずHTTPステータスコードを確認し、次にcodeまたはtypeを確認してください。
一般的なステータスコード
400 Bad Request
- リクエストボディが空、または有効なJSONではない、
modelが欠落している、またはフィールドの型が正しくない場合。 - 動画リクエストにモデルがサポートしていないフィールドが含まれている場合:
video_input_unsupported。fieldがどのフィールドかを示します。 - モデルサービスがリクエスト内容を拒否した場合:
upstream_rejected。モデルサービスから返されたupstream_codeが含まれる場合があります。
401 認証失敗
| code | 意味 | 対処方法 |
|---|---|---|
API_KEY_REQUIRED | APIキーが提供されていない | Authorization: Bearer <YOUR_API_KEY>リクエストヘッダーを確認してください |
INVALID_API_KEY | APIキーが無効 | コンソールでキーを確認するか、新しいキーを作成してください |
API_KEY_DISABLED | APIキーが無効化されている | コンソールで再有効化してください |
APIキーをURLクエリパラメータとしてのみ渡した場合、有効な認証とはみなされず、API_KEY_REQUIREDが返されます。
402 残高不足
insufficient_credits: アカウントの利用可能残高が不足しています。コンソールの「Top up」ページでチャージしてから再試行してください。
403 Forbidden
| code | 意味 | 対処方法 |
|---|---|---|
API_KEY_EXPIRED | APIキーの有効期限切れ | コンソールで有効期間を更新するか、新しいキーを作成してください |
ACCESS_DENIED | 送信元IPが許可リストにない、またはブロックリストに含まれている | キーのIP設定を確認してください |
404 Not Found
model_not_found: モデル名のスペルが間違っているか、アカウントがこのモデルを使用できません。- モデルが呼び出されたAPIをサポートしていない（例: チャットモデルで画像生成エンドポイントを呼び出した場合）。
- リクエストパスが存在しない。多くの場合、base_urlに
/v1が欠落しています。
409 動画準備未完了
video_not_ready: 動画はまだ生成中です。後ほど再度ダウンロードをリクエストしてください。
413 リクエストボディが大きすぎる
リクエストボディが制限を超えています。リクエスト制限を参照してください。
429 クォータまたはレート制限超過
| 状況 | レスポンス | 対処方法 |
|---|---|---|
| APIキーの合計クォータを使い切った | API_KEY_QUOTA_EXHAUSTED | コンソールでクォータを増やすか、使用済みクォータをリセットしてください |
| 同時リクエスト制限を超過 | gateway_concurrency_limit | 同時実行数を減らし、待機後に再試行してください |
| モデルサービスのレート制限 | upstream_rate_limited | 待機後に再試行してください。レスポンスにRetry-Afterが含まれる場合は、指示に従って待機してください |
5xx サービス一時利用不可
- 502
upstream_unavailable: モデルサービスが一時的に利用できません。 - 503
no_available_accountまたはService temporarily unavailable: 現在利用可能なサービス容量がありません。
これらのエラーは後で再試行できます。指数バックオフを推奨します。
リクエスト制限
| 制限 | 値 |
|---|---|
| リクエストボディの最大サイズ | 100MB |
| 応答なしの待機時間 | アクセスレイヤーの読み取りタイムアウトは600秒です。モデルAPIまたはクライアントがより早くタイムアウトする場合があります。これはタスク全体の最大実行時間ではありません |
| 利用状況のクエリ範囲 | 最大90日間 |
キーレベルの合計クォータ、有効期間、IP制限はコンソールで設定します。アカウントレベルのリクエストレートと同時実行数の制限はプラットフォームが設定し、超過した場合は429が返されます。
課金と利用状況
- API呼び出しは、毎回USD残高から実際の使用量に基づいて課金されます。残高はZaiDrama作成と共有されます。残高とチャージについては、アカウント、クレジット、サポートを参照してください。
- 各モデルのUSD単価（100万トークンあたりまたは課金単位あたり）は、コンソールの「Pricing」で確認できます。
- 動画タスクは、動画が正常に生成されたときに1回だけ課金されます。
- 呼び出しの詳細は、コンソールの「Usage」で確認できます。各レコードには、モデル、API、ストリーミングかどうか、トークン数、コスト（USD）、所要時間が含まれ、CSVとしてエクスポートできます。
- 残高が不足している場合、返されるメッセージは
余额不足：这次调用至少需要 $x，当前可用 $y，请充值后再试のようになります。
トラブルシューティングチェックリスト
- すべてのリクエストが404を返す: base_urlが
https://api.ourzai.com/v1（/v1付き）と書かれているか確認してください。 - 401: リクエストヘッダーが
Authorization: Bearer <YOUR_API_KEY>であるか、APIキーが完全で無効化されていないかを確認してください。 - 特定のモデルが404を返す: モデル名が「Pricing」と一致しているか、そのモデルが呼び出しているAPIをサポートしているかを確認してください。
- 402、403、429: 利用可能残高、APIキーの合計クォータ、有効期間、IP設定、同時実行数を確認してください。
- 動画が
pendingのまま: 動画生成には時間がかかります。間隔を空けてポーリングしてください。expiredはタスクが期限切れになったことを意味し、再送信する必要があります。 - それでも解決しない場合: 発生時刻、呼び出したAPI、モデル名、エラーレスポンスを添えてsupport@ourzai.comまでメールでお問い合わせください。APIキー全体を含めないでください。