Pro API：制限、エラーコード、ベストプラクティス

上限

すべてのキーには3つの上限があります。同時レンダリング数（デフォルト2）、1分あたりの送信数（デフォルト60）、そして設定した場合は1日のクレジット上限です。

上限を超えると、レスポンスは 429 になり、Retry-After ヘッダーに秒単位の待機時間が返されます。拒否された呼び出しには費用は発生しません。 上限のカウントに使用される「1日」はUTC基準です。

長尺動画には2つの独自の上限があります。1シーケンスあたり30ショットとライセンスごとに同時進行5シーケンスです（Videosを参照）。

キャラクターには1つの上限があります。アプリで作成したものを含め、Proライセンスあたり50件です。また、1年間使用されなかったキャラクターは削除されます（Charactersを参照）。ロケーション、オブジェクト、動物はそれぞれ個別にカウントされ、独自の上限があります。Proライセンスあたり50件（個人ライセンスはアプリ内で10件）で、同じく1年間未使用の場合は削除されます（ロケーション、オブジェクト、動物、スタイル、衣装を参照）。

Face swapには2つの独自の上限があります。1回のレンダーあたり最大20秒のパッセージと、サーバーが同時に処理できる動画は2本です。超過した場合のレスポンスは 429 server_busy で、Retry-After の後にリトライしてください（Face swapを参照）。MCP経由のトランジション付きFace swapは、動画全体で最大60秒、サーバーで同時に2件までです。それを超えると、ツールが数分後に再試行するよう求めます。

弊社のGPUカードはアプリユーザーと共有されています。ビジー状態の場合、レンダリングはレンタルGPUに振り向けられ、同じ料金・同じAPIで処理されますが、起動時に数十秒の追加時間がかかります。

エラーコード

コード	error	内容と対処法
400	prompt_required	プロンプトを追加してください。
400	forbidden_content	コンテンツフィルターがプロンプトを拒否しました。
400	invalid_seed	seed は0から4294967295の整数である必要があります。
400	image_required, inpaint_images_required	このモードには image_b64 が必要です。inpaint の場合は mask_b64 も必要です。
401	key_required, invalid_key	ヘッダーがないか、キーが不明です。
402	insufficient_credits	このレンダーに必要な残高が不足しています（cost に金額が示されます）。レスポンスには buy_url（ライセンスのクレジット購入ページ）が含まれます。進行中のレンダーやトレーニングは完了まで料金を予約します。engaged に保留中のクレジット数が示されます。
402	confirmation_required, payment_declined	登録済みのカードでの購入（POST /credits/purchase）で、銀行が確認を求めているか、支払いを拒否しました。通常の購入リンク buy_url を使ってください。
409	agent_not_allowed, no_saved_card, monthly_cap_reached	登録済みのカードでの購入で、エージェントに購入が許可されていない（アカウントページの自動チャージ）、カードが登録されていない、または購入すると月間上限を超えます。buy_url を使ってください。
409	topup_in_progress, purchase_in_progress	登録済みのカードで別の支払いが進行中です。終わるまでお待ちください。
400	unknown_pack	不明なパック、または範囲外か刻み単位でない任意のクレジット数での購入です。
503	payment_unavailable	支払いを確認できませんでした。引き落としが行われたかどうか分かりません。すぐに再試行しないでください。引き落としが行われていれば、クレジットは付与されます。
403	key_disabled, key_revoked, key_expired	キーが無効化、失効、または期限切れです。アプリで新しいキーを作成してください。
403	license_revoked, license_not_pro	ライセンスが失効しているか、Proアカウントではありません。
403	missing_scope	キーに必要な権限がありません。scope に対象の権限名が示されます。
403	unknown_lora	アカウントに存在しないキャラクターです。
404	media_unavailable	ファイルが見つかりません。再送信してください。
404	unknown_lora	DELETE /loras/{name} において、そのアカウントに該当する名前のファイルがありません。コードに注意してください。レンダーが他のアカウントのキャラクターを要求した場合は同じ名前で 403 が返されます。
411	size_required	Content-Length なしのLoRAアップロードです。ボディは生データなので、サイズを事前に宣言する必要があります。
413	file_too_large	LoRAが800 MBを超えているか、単一アップロードで90 MBを超えています。分割して送信してください。JSONボディを含まない単純な 413 は別の問題で、リクエストがAPIに届いていません。アップロードのセクションを参照してください。
413	part_too_large	1つのパートがセッションで通知された max_part_size を超えています。
404	unknown_upload_session	uploadId が存在しないか、セッションが放棄（6時間）またはパートの拒否によりキャンセルされました。
503	upload_refused, part_refused	アップロード中にストレージに到達できませんでした。リトライしてください。
507	storage_full	サーバーのストレージ（LoRA、または進行中のシーケンス）に空きがありません。チームに通知済みです。しばらくしてからリトライしてください。
415	invalid_safetensors	アップロードされたファイルがsafetensors形式ではありません。
415	incompatible_lora	このLoRAは別のアーキテクチャ向けです（architecture に記載）。画像はKrea 2のみ、動画はLTX 2.5または2.3に対応しています。ファイルは保存されず、クォータも消費されません。
413	lora_quota	アカウントのLoRAストレージが上限（20ファイルまたは10 GB）に達しています。レスポンスに残量が示されます。ファイルを削除してスペースを確保してください。
413	image_too_large	ソース画像またはマスクがデコード後に12 MBを超えています。
429	too_many_concurrent_renders, rate_limited, daily_cap	上限に達しています。Retry-After を確認してください。
429	daily_credit_cap	キーの1日のクレジット上限に達しました（cap、spent、cost が示されます）。
502	submission_failed, status_failed	レンダー側で障害が発生しました。数秒後にリトライしてください。
503	license_check_failed	現在アカウントを確認できません。1分後にリトライしてください。
400	invalid_extend_frames	extend_frames が9、17、25、33、41、49のいずれでもない延長、またはそのフレーム数と一致しない extend_video です。
400	extension_with_transition	consistency が enhanced の場合を除き、延長とトランジションは同時に指定できません。end_image を削除するか、enhanced consistencyをリクエストしてください。
400	extension_too_short	延長の length は新しいフレームのみをカウントし、最低9以上である必要があります。
404	clip_unavailable	延長対象のクリップはもう利用できません。早めに延長するか、extend_video でクリップの末尾を送信してください。502 の場合は読み取りに失敗しています。リトライしてください。
404	unknown_clip	延長対象のクリップが別のライセンスに属しています。
404	unknown_sequence	シーケンスが存在しないか、別のライセンスに属しているか、期限切れです。
400	job_id_required, empty_sequence	job_id なしの POST /sequences/{id}/clips、またはショットが存在しないシーケンスのエクスポートです。
409	not_exported_yet	エクスポート前に GET /sequences/{id}/file が呼ばれました。先に POST /sequences/{id}/export を呼び出してください。
404	unknown_export	プロジェクトフォルダーのエクスポート：不明なレンダー、別ライセンスのもの、または24時間以上前に送信されたもの。ZIPは削除済み（最初のダウンロードから45分後、最大2時間）。
409	export_in_progress	プロジェクトフォルダーのエクスポートは1ライセンスにつき同時に1件まで。
413	export_too_large	プロジェクトフォルダーが2 GBを超えています。ショットを1つずつエクスポートしてください。
400	unknown_reference	プロジェクトフォルダーのエクスポート：exclude_referencesの項目がエクスポートのどのリファレンスも指していません（id、名前、@メンションのいずれにも一致しない）。
400	invalid_export_options	プロジェクトフォルダーのエクスポート：真偽値でないオプション、テキストのリストでないexclude_references、またはinclude_mediaなしのinclude_film。
500	export_failed	エクスポートに失敗しました（理由はdetail）。料金は発生しません。再試行してください。
422	resolution_mismatch, unreadable_clip	手動で登録したレンダー（POST /sequences/{id}/clips）の解像度がシーケンスと異なる、または読み取れません。
409	missing_shot	ショットがまだ完了していないか、利用できなくなっています（job_id に対象が示されます）。完了を待ってから再度エクスポートしてください。
409	sequence_exported	シーケンスはすでに組み立て済みです。
409	audio_mismatch	無音のシーケンスに音声付きショットを追加しようとしているか、その逆です。
413	extend_video_too_large	送信したクリップの末尾が8 MBを超えています。
413	too_many_shots	シーケンスあたり最大30ショットです。
422	unreadable_tail	送信または読み取ったクリップの末尾が読み取り可能な動画ではありません。
422	assembly_failed	ショットの解像度が異なるか、一部のショットにのみ音声があります。
503	ultra_unavailable	Ultraモードは現在利用できません。後でリトライするか、quality なしでレンダーしてください。
503	ultra_4k_unavailable	Ultraで4Kサイズを指定しています。4Kの提供は終了しました。動画は1080p（1920 x 1088）までです。
400	ultra_incompatible	Ultraでトランジション（end_image）を指定しています。
400	extension_4k	以前の4Kクリップの継続です。4Kの提供は終了したため、4Kクリップは延長できません（quality: "max"ありはultra_4k_unavailable）。1080p以下のクリップを延長してください。
400	resolution_above_quality	quality: "max" なしで1080p（1920 x 1088）を超えるサイズを指定しています。1080pがすべてのモードの上限です。
400	invalid_keyframes, invalid_keyframe_time, keyframes_mode	キーフレームが範囲外です。4枚超、無効な画像またはstrength、クリップ外のタイミング、0.5秒未満の間隔、Quality以外のモード（Ultra、Multi-Ref）、または consistency が enhanced でない延長です。
400	invalid_consistency, consistency_mode	consistency が standard または enhanced 以外です。UltraまたはMulti-Refでenhanced consistencyをリクエストしています。
400	consistency_explicit	enhanced consistencyで処理できないプロンプトです。20秒超（end_image がある場合は15秒超）、延長、またはシーケンス内（より短い単一ショットはstandard consistencyでレンダーされます）。短くするか、standard を使用してください。
403	consistency_licensed_only	Enhanced consistencyはライセンス保有者専用です。
503	consistency_unavailable	Enhanced consistencyは現在利用できません。後でリトライするか、standard でレンダーしてください。
409	consistency_mismatch	ショットの consistency がシーケンスのものと異なります。
422	encoding_mismatch	手動で登録したレンダー（POST /sequences/{id}/clips）の consistency が既存のショットと異なります。
400	invalid_fps, fps_requires_fixed_duration, extend_fps_mismatch	モードでサポートされていないフレームレート（fps）です（detail に対応リストが示されます）。自動尺でenhanced consistencyを30 fps超で使用しています（duration_auto を false にして length を指定してください）。前のクリップと異なるフレームレートで延長しています。
409	sequence_fps_mismatch	ショットのフレームレート（fps）がシーケンスのものと異なります。
503	keyframes_unavailable	キーフレームは現在利用できません。keyframes なしでレンダーしてください。
429	too_many_sequences	ライセンスあたり同時進行できるシーケンスは最大5件です。1件をエクスポートするか、期限切れになるまで待ってください。
400	invalid_name, invalid_kind, invalid_photo_role, outfit_too_long, invalid_role	キャラクターフィールドが範囲外です（Charactersを参照）。
400	image_too_small	写真の長辺が1024 px未満です。
415	unsupported_image_format, unreadable_image	写真またはロケーション画像が読み取り可能なJPEG、PNG、WebP形式ではありません。
404	unknown_character	character_id がライセンスに存在しないか、削除済みです（1年間未使用、またはアプリで削除）。
409	character_limit	キャラクターの上限（max）に達しています。1件削除してください。
409	character_busy	ビューの生成中です。status が pending でなくなるまで待ってください。POST /characters の場合は、同じ作成リクエストを登録中です。数秒後に再送してください。
409	photo_view, empty_character, single_image_sheet	元の写真から生成されたビューは再生成できません。またはキャラクターに読み取り可能なビューがありません（ストレージが読み取りを拒否した場合は 503 storage_unavailable、再試行してください）。または1枚の画像として取り込んだシート（そのまま保持）：ビューは作り直せず、新しいシートの着せ替えにも使えません（ビュー4または1を送ってください）。
409	app_character	アプリで作成したキャラクターまたはシートに instruction またはアップロードしたビューを使用しています。APIで作成したキャラクターとシート専用の操作です。
400	instruction_too_long	instruction が200文字を超えています。
400	outfit_or_views_required	outfitもviewsもないシートの追加です。生成する衣装か、ビューを指定してください。
400	views_required	generate: falseでのシートの追加です。ビューを1つ以上指定してください。
409	source_sheet_empty	全身ビューもバストもないシートの追加で、キャラクターにも出発点となる全身ビューやバストがありません。どちらかをviewsで送ってください。
404	unknown_sheet	DELETE /characters/{id}/sheets/{sheet_id}で削除できるのは、APIで追加したシート（sheet_origin api）だけです。
404	unknown_subject	subject_id がライセンスに存在しないか、1年間未使用で削除済みです。
409	subject_limit	サブジェクトの上限（max）に達しています。ロケーション、オブジェクト、動物、スタイル、衣装は合算されます。1件削除してください。
409	empty_subject	読み取り可能な画像がないサブジェクトです。
400	invalid_type, description_too_long, invalid_images	サブジェクトフィールドが範囲外です（ロケーション、オブジェクト、動物、スタイル、衣装を参照）。
400	invalid_image	長辺が最低512 pxの読み取り可能なJPEG、PNG、WebP形式ではないサブジェクト画像です（index に対象が示されます）。
400	description_required, invalid_views, invalid_view, invalid_count, too_many_images, prompt_too_long, invalid_instructions	サブジェクトの生成：description、prompt、開始画像のいずれもありません。その種類にないビューキーです（detail に一覧があります）。count が1〜6の範囲外か、開始画像を含めて6枚を超えています。prompt が2000文字を超えています。instructions が空、長すぎる、または複数のビューに対して指定されています。
409	subject_busy, subject_not_generated, view_exists, views_exist, start_image_missing, start_image_imported	このサブジェクトではすでにシリーズが進行中です。画像から作られたサブジェクトです（/images で画像を追加してください）。すでに作成済みのビューです（やり直してください）。ビューが派生している開始画像をやり直そうとしています。失敗した開始画像を先にやり直す必要があります。インポートした開始画像はやり直せません。
404 / 503	unknown_view, generation_unavailable	一度もリクエストされていないビューです（追加してください）。サブジェクトの生成は現在サーバーで利用できません。後でもう一度お試しください。
400	multiref_characters_required, multiref_incompatible, multiref_mode, multiref_format, invalid_length	Multi-Refが範囲外です。1から4のキャラクター（Ultraでは12）、延長やトランジションなし、Multi-Ref Videoのフォーマットと尺を確認してください。
400	duplicate_name, invalid_strength, unknown_mention	同じ名前のキャラクターが2件存在します。strength が0から2の範囲外です。プロンプトにキャラクターなしの @Name が含まれています（mentions に一覧が示されます）。
400	voice_requires_audio, voice_slot	音声なし（"audio": true）でキャラクターボイス（voice_b64）を指定しています。または characters[0] と characters[1] 以外のキャラクターに指定しています（エンジンはボイス2件に対応）。index に対象が示されます。
400	invalid_voice_choice	Face swapでvoiceがcharacter、original以外、またはMulti-Ref Videoでcharacters[].voiceがcharacter、generated以外です。
413	audio_too_large	キャラクターボイスが4 MBを超えているか、Face swapで2 MBを超えています。最初の5秒のみ使用されます（Face swapでは20秒）。短いサンプルを送信してください。
415	unsupported_audio_format	キャラクターボイスが読み取り可能な音声ファイル（WAV、MP3、OGG、FLAC）ではありません。
400	multiref_too_many_references, invalid_subject_type	Ultra以外で、キャラクター、オブジェクト、動物の合計が4件を超えています。サブジェクトが誤ったフィールドに渡されています（subjects にロケーション、location にオブジェクト、styles 以外にスタイル、outfits 以外に衣装）。
400	invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size	Create an image: count は1または2、view は1〜5でシートに存在すること、lora_pass は0.3〜0.9、サブジェクトの image はその画像のいずれか、幅と高さは256〜2048。
400	character_not_ready	Create an image: キャラクターの選択したビューにまだ画像がありません。
503	multiref_image_disabled	このサーバーでは画像の作成（Create an image）はまだ公開されていません。
400	multiref_ultra_only, multiref_too_many_images, unknown_wearer	Ultra以外のMulti-Refでスタイル、衣装、モーションを使用しています。Ultraで画像が30枚を超えています。worn_byがどのキャラクターも指していません。
400	invalid_motion, invalid_motion_mode, unreadable_motion, motion_missing	motionにmotion_idもvideo_b64もありません。modeがcameraでもchoreographyでもありません。動画が読み取れないか、4〜30秒の範囲外です（input_video_out_of_limits）。motion_idがアップロードされていません（PUTがありません）。
404 / 409	unknown_motion, motion_already_used	motion_idが不明、使用済み、または2時間を超えています。動画をもう一度アップロードしてください。
413 / 503	motion_too_large, motion_not_open, motion_mode_unavailable	モーション動画が20MBを超えています（480pに変換後は20MB）。モーションはまだ公開されていません（ultra.motion_per_secondがnull）。modeがまだ公開されていません。
409	extension_link_expired	ライセンスが認識しないextend_job_id、または24時間を超えたUltraショットです。元のファイルをアップロードし（POST /extensions）、extend_upload_idを渡してください。
400	extension_real_face	Ultraで延長する動画がUltraモードでレンダリングされたものではなく（たとえば別のモードのレンダリング）、リアルな顔が映っています。課金はありません。Qualityモードで延長するか、Ultraでショットを作り直してください。
400	extension_ultra_only, extension_ultra_options, invalid_extension_direction, extension_backward_sequence, extension_tail_quality_only	Ultra延長の条件外です。quality: "max"なしのextend_upload_idやbackward（またはUltraでないクリップからの延長）、開始画像・リファレンス・モーション・enhanced consistencyとの併用、forwardとbackward以外の方向、シーケンス内のbackward、Ultraでのextend_video。
400	extension_too_large, unreadable_extension, extension_upload_missing	アップロードした動画が1080pを超えています。MP4が読み取れないか、4〜30秒の範囲外です（input_video_out_of_limits）。ファイルがアップロードされていません（PUTがありません）。
400	input_video_out_of_limits	Ultraモードに送った動画（モーション、延長する動画）が上限・下限を外れています。レンダリング前に検査され、請求はありません。limitがどの条件かを示します（duration：4〜30秒、total_duration：参照音声と合わせて30秒、count：10、size：200MB、format：MP4またはMOV、fps：24〜60、pixels：幅×高さ409,600〜8,295,044、aspect_ratio：0.4〜2.5）。value、min、maxも返ります。
404 / 409	unknown_extension_upload, extension_upload_used	extend_upload_idが不明、2時間を超えている、または使用済みです。ファイルをもう一度アップロードしてください。
413 / 503	extension_too_heavy, extension_not_open, extension_backward_unavailable	ファイルが60MBを超えています。Ultra延長はまだ公開されていません（ultra.extend_per_secondがnull）。後方への延長はまだ公開されていません。
413	references_too_large	準備済みのビューがレンダーの予算を超えています。キャラクター数を減らすか、フォーマットを小さくしてください。
400	video_required, character_required	video_b64 なし、または character_id なしのFace swapです。
413	video_too_large	Face swapの動画が20 MBを超えています。事前にトリミングまたは圧縮するか、最大95 MBに対応しているMCPツールの tendre_face_swap を使用してください。
415	unreadable_video	Face swapの動画が読み取り可能なMP4、MOV、WebM、MKV形式ではありません。
400	invalid_start, invalid_duration, passage_too_short	Face swapのパッセージが範囲外です。start が0未満または動画の末尾を超えている、duration が0.5から20秒の範囲外、またはパッセージが0.5秒未満です。
400	invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part	Face swapフィールドが範囲外です。zone が tight、normal、wide 以外、part が full、head 以外、likeness が0.5から2の範囲外、scene が400文字超、description が360文字超、name が60文字超です。
413	face_swap_too_large	準備後もパッセージが重すぎます。duration を短くしてください。
429	server_busy	サーバーはすでに2件のFace swap動画を処理中です。Retry-After（20秒）の後にリトライしてください。MCPアップロードリンクは待機ファイルが多すぎる場合に 503 として同じコードを返します。数分後にリトライしてください。
503	face_swap_unavailable, face_swap_price_missing	Face swapは現在利用できないか、料金が設定されていません。後でリトライしてください。
503	creation_unavailable, multiref_unavailable, storage_unavailable	サービスは現在利用できません。後でリトライしてください。
500	internal_error	サーバー側で予期しない障害が発生しました。リトライし、繰り返す場合はご連絡ください。

秒単位課金のUltra (Ultra):

コード	error	内容と対処法
400	resolution_outside_ultra	1080pを超えています：480p、720p、1080pのいずれかにしてください。
400	engine_refused	エンジンがテキストまたは画像を拒否しました。理由は detail、コードは code にあります。課金はありません。言い換えてください。
502	engine_unavailable	エンジンが応答しません。数分後に再試行してください。課金はありません。
409	render_in_progress	すでに計算中のレンダリングのキャンセル：止まらず、納品され課金されます。
400	invalid_references, references_too_large, multiref_ultra_options, multiref_ultra_explicit	UltraのMulti-Ref：参照画像が読み取れない、または大きすぎる（合計20MBまで）、あるいはサポートされていないオプションです。
403	multiref_ultra_unavailable	秒単位課金のUltraのMulti-Refは、このアカウントではまだ利用できません。

エラー名はAPIが返す正確な文字列です。message は変更される可能性があるため、エラー名で判定してください。

エラーではないレスポンスが1つあります。ビューが1件しかないキャラクターでMulti-RefレンダーまたはFace swapを行った場合、処理は続行されますが、warnings に limited_likeness の警告が含まれます（{ "code": "limited_likeness", "character_id": "...", "detail": "..." }）。 似顔絵の精度が制限されます。忠実な再現には、キャラクターの7つのビューを作成してください。

Ultraで9〜12体のキャラクターを使うMulti-Refレンダーも処理は続行されますが、warnings に many_characters の警告が含まれます。一部が欠けたり混ざったりする可能性があります（推奨は8体）。

ベストプラクティス

• ポーリングは3秒ごとに行い、それ以上頻繁に行わないでください。 キューは共有されており、頻繁なポーリングは誰の利益にもなりません。
• ステータスが completed になったらすぐにダウンロードしてください。 ファイルはアーカイブされません。
• プロンプトは英語で記述してください。 動画の場合は静止した状態ではなく動きを説明してください。
• 用途ごとにキーを分け、サーバー上で使用するすべてのキーに1日のクレジット上限を設定してください。 上限付きのキーが漏洩しても、損失は1日分だけです。残高全体には影響しません。
• 429 は通常の動作として扱い、エラーとみなさないでください。 Retry-After を待って処理を続けてください。
• 応答前に切れた接続には料金がかかりません。 画像や動画の送信に応答がない場合（プロキシのタイムアウト、エラー 524、プログラムの停止など）、レンダリングは開始されないか、すぐにキャンセルされ、課金もされません。そのままリクエストを再送してください。画像のバッチ（count）では、すでに作成されたレンダリングもキャンセルされます。キャラクターの作成は続行されます。同じリクエストを再送すると同じキャラクターが返され、二重に課金されることはありません（Charactersを参照）。

プロンプトはアプリと同様に、安全上の理由から弊社側でログに記録されます。