レート制限とクォータ

プラットフォームの制限はいくつかの種類に分かれており、発生時の表示もそれぞれ異なります。どの種類なのかを区別して初めて、迅速に対処できます。

制限の種類	発生時の表示	対処方法
リクエスト頻度（レート制限）	HTTP `429`「リクエストが多すぎます」	バックオフしてから再試行し、並行して再試行しない
非同期タスクの並行数	HTTP `429`、`task_concurrency_exceeded`	既存のタスクが完了してから送信する
Key のクォータ	残高/クォータ不足のメッセージ、タスクは作成されない	チャージする、Key のクォータを調整する、またはリクエストを小さくする
アカウント残高	残高が今回の推定消費をカバーできない旨のメッセージ	ウォレットでチャージする
素材の容量	素材送信時の形式とサイズの検証	ファイルを修正するか `image_url` に変更する

リクエスト頻度の制限

プラットフォームにはリクエスト頻度の制限があります。ポーリングが速すぎる、並行数が高すぎる、または短時間に大量の再試行を行うと、制限に達する可能性があります：

{ "error": { "code": "...", "message": "请求过于频繁" } }

HTTP ステータスは 429 です。

正しい対処：

429 以外のステータスコードをむやみに再試行しない：

動画などの非同期タスクは並行上限の制約を受け、単一アカウント単位とプラットフォーム全体単位に分かれます。上限に達すると HTTP 429 を返し、エラーコードは task_concurrency_exceeded で、メッセージには「現在 N 件 / 上限 M 件」が示されます。

発生した場合は以下のように対処してください：

一括送信の前に、業務のバックエンドでキュー管理を行うことをおすすめします。一度にすべてを送信するのではなく、処理中のタスク数を制御してください。

クォータと残高は2 層の制限です：

階層	説明
Key のクォータ	コンソールの「API キー」でその Key に設定する使用量の上限と有効期限
アカウント残高	LocoPal アカウント全体の利用可能残高、プランのクォータ、またはクレジット

非同期タスクは送信前に残高が今回の推定消費をカバーできるかを検証します。不足している場合は読み取り可能なメッセージを返し、 タスクを作成しません。そのため、この場合は費用が発生しません。

対処方法：

業務のバックエンドで残高の事前判定を行い、エンドユーザーに分かりやすいメッセージを表示することをおすすめします。プラットフォームのエラーをそのままユーザーに投げ返さないでください。

素材エンドポイントはアップロードデータに対して検証を行います：

制限	表示	対処
アドレスの形式	`image_url 必须是可公开下载的 http(s) 地址…`	パブリックインターネットから直接ダウンロードできる `http(s)` アドレスに変更する
1 回につき 1 種類のみ送信	`image_url 与 data_url 只能提交一个`	フィールドを 1 つだけ残す
データサイズ	`图片数据无效或超过 20MB`	画像を圧縮するか `image_url` に変更する
グループの種類	`素材分组不存在或不是虚拟素材分组`	画像は `virtual` グループにのみ送信できる
名前の長さ	グループ名は空にできず、64 文字以内。説明は 300 文字以内	名前または説明を修正する

素材の審査が完了していないことはエラーではありません：照会が 200 と status が Processing を返す場合は、同じ素材 ID でポーリングを続けてください。重複して送信しないでください。

非同期タスクの照会では費用は発生しませんが、ポーリングが密すぎるとレート制限が発生します。

ポーリングには総時間の上限を設けてください。上限に達したら照会を停止し、ユーザーにタスク ID を返して、後で ID を使って照会を続けられるようにします—— タスクを再作成しないでください。

プラットフォームは同一のリクエストを自動的に統合しません。プロンプト、パラメータ、参照素材が完全に同じでも、主体的に送信するたびに新しいタスクと新しい結果が作成され、それぞれ課金されます。

そのため：