Clipwright

Clipwright API

スクリプトをリップシンク付きのUGC動画に変換する、またはスクリプトや短い概要を、冒頭のアニメーションクリップと画像シーンにナレーションを重ねた顔出しなし動画に変換する、単一のHTTP APIです。エージェントによる操作を想定して構築されています。各呼び出しは単一のJSONリクエストで、拒否する場合は次に何をすべきかを伝え、どこにも公開されることはありません。このページの内容はすべて、https://clipwright.io/docs.md にある1つのMarkdownファイルであり、テキストを読むエージェント向けの短い仕様書でもある https://clipwright.io/llms.txt です。https://api.clipwright.io/openapi.json にあるOpenAPI 3.1ファイルは、APIが検証に使用するスキーマから作成された、機械可読なREST仕様です。

認証

すべての呼び出しは https://api.clipwright.io に送信し、1つのヘッダーにキーを含めます。

Authorization: Bearer cw_your_key_here

• キーは cw_ で始まり、発行時に一度だけ表示されます。保存するのはダイジェストのみのため、紛失したキーは復元できず、再発行が必要です。
• ダッシュボードの https://app.clipwright.io/api-keys でキーを発行・失効できます。失効は次のリクエストから有効になります。
• @clipwright/cli と @clipwright/mcp-server は環境変数 CLIPWRIGHT_API_KEY からキーを読み込みます。@clipwright/sdk では引数として渡します。
• キーがない場合、または失効済みのキーを使った場合は、課金が発生する前に401で拒否されます。

03

料金

• プレーンなスクリプトから make_ugc を実行する場合：完成動画の秒数ごとに10クレジット。秒単位で切り上げられ、納品した動画は最低50クレジットです。
• セグメントまたは挿入素材を使って make_ugc を実行する場合：顔が画面に映っている秒数ごとに9クレジット（OmniHumanでレンダリングしたテイクは22クレジット）、さらに動画の秒数ごとに1クレジット、ライブアバター呼び出しの静止画ごとに400クレジット。納品した動画は最低50クレジットです。挿入素材、オーバーレイ、ウィンドウ、テンプレートで顔が隠れていてもカウントされます。ファイルが納品されなかった実行は一切課金されません。顔が映っている時間は動画全体で合算し、セグメントごとではなく一度だけ切り上げます。これらのフィールドには長尺利用の承認が必要です。承認されていない場合は、課金前にフィールド名を示して拒否されます。
• quality medium で create_actor を実行する場合：ポートレートに4クレジット（自分の画像を portrait として渡した場合は無料。既存のアクターを from_actor_id で指定して表示する場合は4クレジット）、追加フォーマットごとに8クレジット。
• quality high で create_actor を実行する場合：ポートレートに45クレジット（自分の画像を portrait として渡した場合は無料。既存のアクターを from_actor_id で指定して表示する場合は12クレジット）、追加フォーマットごとに18クレジット。
• make_faceless：生成する画像1枚につき7クレジット、冒頭クリップに49クレジット、納品動画の秒数ごとに1クレジット。最低50クレジットです。duration_seconds に対する見積もり額が支払いの上限です。30秒なら212クレジット、90秒なら356クレジットです。自分の画像は課金対象外で、字幕によって料金が変わることはありません。
• クレジットはパックで購入します。1000クレジットは$10.00、2750クレジットは$25.00、6000クレジットは$50.00です。1回の支払いにつき1パックを購入でき、購入したクレジットに有効期限はありません。

使う前に確認しましょう。各スキルの見積もりエンドポイントは無料です。見積もりの意味はスキルによって異なります。

• make_ugc：見積もりはスクリプトの語数から算出した概算です。実際の課金は完成動画の測定値に基づきます。プレーンスクリプトの場合は動画の長さ、顔が映る時間を基準とする場合は顔が映る秒数で計算されるため、請求額は見積もりを上回ることも下回ることもあります。
• create_actor：見積もりはリクエストしたすべてのフォーマットを対象とし、支払いの上限額となります。ポートレートと実際に公開されたバリエーションに対して課金されます。生成されなかったフォーマットは warnings[] に記載され、課金されません。
• make_faceless：見積もりはリクエストした duration_seconds を対象とし、支払いの上限額となります。動画の長さはナレーションに必要な時間に合わせられ、最低25秒（解説動画の場合はナレーションのみの長さ）です。通常はその長さに最大25%を加えた時間、かつ90秒以内ですが、ナレーションがそれより長い場合は最後まで続きます。実際に納品された長さに対して課金され、見積もり額を超えることはありません。

実行に失敗した場合の料金も、スキルによって異なります。

• プレーンなスクリプトから make_ugc を実行する場合：動画の発注後に失敗した実行は課金されます。発注前に失敗した場合は課金されません。また、こちらで停止した場合、処理が失われた場合、またはこちらで拒否した場合も課金されません。顔が映る時間を基準とする場合、失敗による課金は一切ありません。
• create_actor：アクターが納品されないため、失敗した実行は一切課金されません。
• make_faceless：こちらでチェックに合格しなかったステップを理由に停止した場合も含め、失敗した実行は一切課金されません。レビュー待ちの実行は、解決するまでクレジットの保留が続きます。

04

編集料金

顔出しなし動画のリビジョンは、編集したドキュメントから新たに実行する処理です。POST /v1/runs/{id}/revisions/quote で無料見積もりを取得し、POST /v1/runs/{id}/revisions で開始します。

• 新しい画像：7クレジット。
• 新しい冒頭クリップ：49クレジット。
• 新しい冒頭静止画とそのクリップ：56クレジット。
• 何かを生成するリビジョンのレンダリング：リビジョンごとに1回、13クレジット。
• 何も生成しないリビジョン（タイミング変更、削除、自分でアップロードした素材）のレンダリング：13クレジット。
• 有料編集が利用可能になった後、元の動画は完了から364日間、有料で編集できます。
• 同じ元動画に対して同時に実行できるリビジョンは最大1件です。失敗または未完了のリビジョンは最大3件です。
• 納品されたリビジョンには見積もり総額が課金されます。失敗したリビジョンは課金されません。
• 有料編集が利用できない間は、どちらのリビジョンルートも editing_disabled を返し、課金されません。

05

ショット候補の料金

ショット候補とは、顔出しなし動画の1つのショット用に作成する画像またはクリップです。リビジョンで採用または破棄できます。POST /v1/runs/{id}/candidates/quote で無料見積もりを取得し、POST /v1/runs/{id}/candidates で作成します。

• 候補画像：7クレジット。
• 候補の冒頭クリップ：49クレジット。
• 候補の冒頭静止画とそのクリップ：56クレジット。
• 同じ元動画のショット候補は、同時に最大1件まで実行できます。失敗または未完了の候補は最大3件です。リビジョンは別に数えます。
• 納品された候補は、採用するか破棄するかにかかわらず、1単位分が課金されます。失敗した候補は課金されません。
• ショット候補が利用できない間は、3つの候補ルートは editing_disabled を返し、課金されません。

06

エンドポイント

エンドポイント	クレジットを消費	内容
POST /v1/skills/make_faceless/quote	いいえ	この入力での make_faceless 呼び出しの料金を見積もります。料金は発生しません。
POST /v1/skills/make_faceless/run	はい	顔出しなし動画の実行を開始し、run_id をすぐに返します。結果を得るには実行をポーリングしてください。
GET /health	いいえ	API 自体の稼働状況を返します。キーなしで応答します。
GET /	いいえ	サービス名とこのドキュメントへのリンクを返します。キーなしで応答します。
GET /robots.txt	いいえ	クローラーに API ホストをインデックスしないよう指示します。キーなしで応答します。
GET /openapi.json	いいえ	API の検証に使うものと同じスキーマから生成された、この API の OpenAPI 3.1 定義です。キーなしで応答します。
GET /v1/voices	いいえ	make_ugc の voice または voice_id に指定できる音声です。skill=make_faceless の場合は、代わりに make_faceless のナレーション音声を一覧表示します。
GET /v1/template-sounds	いいえ	make_ugc テンプレートでビートごとに再生されるサウンドです。各ビートの再生位置、デフォルト、および template_sounds に指定できるすべての名前を示します。無料です。
GET /v1/moves	いいえ	make_ugc、make_faceless、参照動画のリメイクで、スクリプトの各行に指定する動きのカタログです。視聴者に与える効果、適用される行、使用ごとのクレジット数を示し、フィルターとページ分割に対応します。names では行全体を取得できます。無料です。
GET /v1/account	いいえ	キーに紐づくアカウントの残高、債務、保留額、およびサポートリクエストとフィードバックへの返信を返します。
POST /v1/skills/make_ugc/quote	いいえ	この入力での make_ugc 呼び出しの料金を見積もります。料金は発生しません。
GET /v1/runs/{id}	いいえ	任意のスキルの実行 1 件について、状態、警告、動画 URL を返します。
GET /v1/runs/{id}/shots	いいえ	実行 1 件のショットを返します。各ショットの範囲、セリフ、説明、プレビュー、および実行を編集できるかどうかを示します。
GET /v1/runs/{id}/edit	いいえ	実行 1 件の編集用に保存された下書きと、そのバージョンを返します。バージョン 0 は下書きのない実行で、そのドキュメントは何も変更しません。
POST /v1/runs/{id}/edit	いいえ	読み取った時点のバージョンに対して編集用の下書きを保存します。料金は発生せず、レンダリングも行いません。
POST /v1/runs/{id}/revisions/quote	いいえ	顔出しなし実行の改訂料金を見積もります。ドキュメントまたはショット変更リストで生成される内容と、その費用を示します。料金は発生しません。改訂が成功した場合は見積もり合計が課金され、失敗した場合は課金されません。有料編集が停止中の場合は editing_disabled を返します。
POST /v1/runs/{id}/revisions	はい	ドキュメントから作成する新しい顔出しなし実行として改訂を開始し、見積もりクレジットを保留します。同じリクエストで同じ Idempotency-Key を使うと最初の改訂が返されます。別のキーを使うと別の改訂となり、再度課金されます。改訂が成功した場合は見積もり合計が課金され、失敗した場合は課金されません。有料編集が停止中の場合は editing_disabled を返し、課金されません。
POST /v1/runs/{id}/candidates/quote	いいえ	顔出しなし実行のショット候補 1 件の料金を見積もります。1 つのショット用に作成する画像またはクリップで、採用または破棄できます。料金は発生しません。候補が生成された場合は、採用・破棄にかかわらず 1 単位分が課金され、失敗した場合は課金されません。ショット候補の生成が停止中の場合は editing_disabled を返します。
POST /v1/runs/{id}/candidates	はい	ショット候補の生成を開始し、1 単位分の料金を保留します。候補が生成された場合は、採用・破棄にかかわらず 1 単位分が課金され、失敗した場合は課金されません。同じリクエストと take で同じ Idempotency-Key を使うと最初の候補が返されます。take + 1 を指定すると別の候補が作成され、再度課金されます。ショット候補の生成が停止中の場合は editing_disabled を返し、課金されません。
GET /v1/runs/{id}/candidates	いいえ	顔出しなし実行のファミリーに属するショット候補を古い順に返します。それぞれの状態、課金額、生成後のプレビューを含みます。ショット候補の生成が停止中の場合は editing_disabled を返します。
DELETE /v1/runs/{id}/media	いいえ	完了した実行のファイルを削除します。以後、そのファイルへのリンクは提供されず、7 日後にストレージから消去されます。実行とその課金記録は残ります。別の未完了実行がファイルを使用中の場合は run_media_in_use を返して拒否されます。無料です。
POST /v1/skills/make_ugc/run	はい	動画の実行を開始し、run_id をすぐに返します。結果を得るには実行をポーリングしてください。
GET /v1/public/skills	いいえ	キーなしで、スキルとその入力のカタログを返します。
GET /v1/public/prices	いいえ	すべてのアクションのクレジット料金を返します。単位ごとの固定料金、または入力によって料金が変わる計算式が示されます。正確な数値は見積もりで確認できます。キーなしで無料です。
GET /v1/actors	いいえ	アカウントに保存されたアクターと、make_ugc で指定する ID を返します。
GET /v1/public/actor-previews/{actor_id}/{version}/{file}	いいえ	ライブラリアクターの画像を PNG 形式で返します。リンクは list_actors と見積もりで提供されます。キーなしで応答します。
DELETE /v1/actors/{id}	いいえ	保存済みアクターを削除します。実行中の実行で使用されているアクターは保持されます。
GET /v1/actors/{id}/defaults	いいえ	保存済みアクターについて、挿入映像に登場する人物のデフォルトポリシーを読み取ります。
POST /v1/actors/{id}/defaults	いいえ	保存済みアクターについて、挿入映像に登場する人物のデフォルトポリシーを設定します。実行ごとに上書きできます。
GET /v1/brand-kit	いいえ	アカウントに保存されたデザイン（色、フォント、ロゴ、角、モーション）を読み取ります。保存されていない場合は null を返します。
POST /v1/brand-kit	いいえ	アカウントのデザインを保存します。null を指定すると消去します。デザインも template_theme も指定されていない動画は、このデザインを使って描画されます。無料です。
POST /v1/brand/extract	いいえ	公開サイトから色、フォント、ロゴ、角を読み取り、読みやすいテキストを含む確認用デザイン案を作成します。無料です。1 時間あたりの URL ダウンロード数にカウントされます。
POST /v1/brand-styles/propose	いいえ	気に入った動画の分析結果からスタイル案を作成します。色、顔、角、モーション、トランジションとキャプションの傾向を読み取りますが、ロゴ、キャラクター、フレームは含めません。無料です。保存する前に、その theme_overrides を使ってサンプル静止画を描画してください。
POST /v1/brand-styles	いいえ	確認済みのスタイルを名前付きでブランドキットと並べて保存します。同じ名前で保存すると置き換えられます。動画の下書きでは brand_style に名前を指定します。無料です。
POST /v1/skills/create_actor/quote	いいえ	この入力での create_actor 呼び出しの料金を見積もります。料金は発生しません。
POST /v1/skills/create_actor/run	はい	アクターの実行を開始し、run_id をすぐに返します。結果を得るには実行をポーリングしてください。
POST /v1/uploads	いいえ	画像データを受け取り、署名付き https URL、upload_id、content_digest（元データの SHA-256）を返します。upload_id はワークフローの asset_id として使い、content_digest はそのままコピーしてください。ネイティブの動画およびアクター呼び出しでは url を使います。
GET /v1/uploads	いいえ	改訂で使用できるアップロードを新しい順に返します。画像ごとに 1 件で、それぞれ upload_id、元の content_digest、新たに署名された URL、使用できなくなる時刻を含みます。無料です。
POST /v1/uploads/import	いいえ	公開 https PNG または JPEG をダウンロードし（最大 10 MB、20 秒、リダイレクト 3 回）、同じアップロード形式で返します。プライベートアドレスは拒否されます。アカウントごとに 1 時間あたり 30 回までダウンロードできます。無料です。
POST /v1/uploads/intents	いいえ	宣言された形式、サイズ、sha256 に一致するローカル PNG または JPEG 用の署名付き PUT URL を返します。PUT が完了すると upload_id を使用できます。それまでは生成リクエストに upload_not_finished が返されます。無料です。
GET /v1/uploads/{id}	いいえ	新たに署名された URL と usable_until を含むアップロード 1 件を返します。署名付き PUT の後にファイルを確認します。ファイルが届くまでは upload_not_finished、24 時間経過後は upload_expired が返されます。無料です。
DELETE /v1/uploads/{id}	いいえ	アップロードを削除します。以後、どの呼び出しでも使用できず、同じ画像の別のアップロードが保持されていない限り、ファイルは 7 日後にストレージから消去されます。未完了の実行が使用中の場合は upload_in_use を返して拒否されます。無料です。
POST /v1/assets	いいえ	画像をアカウントアセットとして保存し、削除するまで保持します。run_id、upload_id、公開 https URL、または base64 から保存できます。自分の素材には rights_confirmed: true が必要です。analyze_reference のみで使う参照素材として保存する場合は analysis_only: true を指定できます。この素材はレンダリングや生成には使用できません。アカウントごとにアセット 2000 件、1 GB まで。クレジットパックまたはプランを購入すると 20 GB まで、1 日あたり新規 100 件までです。無料です。
POST /v1/assets/bytes	いいえ	リクエスト本文の PNG または JPEG（最大 10 MB）をアセットとして保存します。role、name、rights_confirmed=true（または analyze_reference のみで使う場合は analysis_only=true）はクエリで指定します。無料です。
GET /v1/assets	いいえ	アカウントの有効なアセットを新しい順に返します。それぞれ 1 時間有効な署名付きリンクと、上限の使用状況を含みます。role と kind で絞り込み、カーソルでページ分割できます。無料です。
GET /v1/assets/{id}	いいえ	1 時間有効な署名付きリンクを含む、有効なアセット 1 件を返します。無料です。
POST /v1/assets/{id}	いいえ	アセットの名前または role を変更します。無料です。
DELETE /v1/assets/{id}	いいえ	アセットを削除します。リストと生成処理からすぐに除外され、7 日経過後に日次クリーンアップでファイルが削除されます。無料です。
GET /v1/public/workflows	いいえ	公開ワークフローのメソッドと、現在利用可能かどうかを一覧表示します。アカウントプランやアカウントの利用許可情報は含みません。
GET /v1/public/workflows/{id}	いいえ	メソッドのガイダンス、制限事項、現在可能な処理を読み取ります。
POST /v1/workflow-plans	いいえ	アカウント所有の変更不可なワークフロー下書きを作成します。料金は発生せず、レンダリングも開始しません。
GET /v1/workflow-plans/{id}	いいえ	アカウントの現在のワークフローリビジョンと準備状況を読み取ります。
POST /v1/workflow-plans/reference-remake	いいえ	参照プロファイルと承認済みスクリプトをコンパイルして、新しい参照リメイク用下書きを作成します。警告には、プランで再現されない内容が示されます。料金は発生せず、生成もレンダリングも開始しません。
POST /v1/workflow-plans/{id}/revisions	いいえ	base_version に対して新しい下書きを保存します。同じリクエストの応答が失われた場合に再試行すると、そのリビジョンが返されます。
POST /v1/workflow-plans/{id}/approve	いいえ	準備完了のリビジョンとそのダイジェストを承認します。料金は発生せず、レンダリングも開始しません。
POST /v1/workflow-plans/{id}/quote	いいえ	承認済みワークフローをネイティブ準備まで見積もります。見積もりは 5 分後に期限切れとなり、クレジットは予約されません。起動時には、実行リクエストの準備完了済み本文に新しい idempotency_key を指定します。
POST /v1/workflow-plans/{id}/run	はい	見積もり済みのネイティブリクエストを正確に 1 回受け付け、レシートと既存のネイティブ Run を返します。見積もりの launch を変更せず本文として送信し、Idempotency-Key ヘッダーには launch.idempotency_key と同じ値を指定してください。同じリクエストが受け付けられると、その実行が再度返されます。
GET /v1/generations/models	いいえ	generate_image と generate_video で使用できるモデルと、測定済みのモード、アスペクト比、解像度、長さ、出力サイズ、画像 1 枚または秒あたりのクレジット数を返します。無料です。生成が停止中の場合は generations_disabled を返します。
POST /v1/skills/generate_image/quote	いいえ	このリクエストで画像 1 枚の料金を見積もります。クレジット数、幅、高さ、警告を返します。料金は発生しません。
POST /v1/skills/generate_image/run	はい	画像生成 1 件を開始し、run_id をすぐに返します。生成された画像は、実行の generation ブロックに格納されます。生成に失敗した場合は課金されません。生成が停止中の場合は generations_disabled を返し、課金されません。
POST /v1/skills/generate_video/quote	いいえ	このリクエストで無音クリップ 1 本の料金を見積もります。秒あたりのクレジット数に長さを掛けた料金、幅、高さ、警告を返します。料金は発生しません。
POST /v1/skills/generate_video/run	はい	クリップ生成 1 件を開始し、run_id をすぐに返します。生成されたクリップは、実行の generation ブロックに格納されます。生成に失敗した場合は課金されません。生成が停止中の場合は generations_disabled を返し、課金されません。
POST /v1/reference-analyses/quote	いいえ	このアセットまたはリンクの分析料金を見積もります。70 クレジット、mode data を指定した場合は 10 クレジット、または同じモードの有効な分析結果がすでにある場合は 0 クレジットです。料金は発生しません。
POST /v1/reference-analyses	yes	MP4アセットの読み取りを開始し、最大120秒の内容をリファレンスプロファイルにまとめます（modeデータを指定した場合は、文字起こし、フック、フレームシートも作成します）。結果はすぐに返されます。同じアセットを同じmodeで指定すると、同じ分析結果が無料で返されます。70クレジット（dataの場合は10）を確保し、成功時に一度だけ課金されます。失敗した場合は課金されません。1時間あたり、新規のfull分析は10件、新規のdata分析は60件までです。
GET /v1/reference-analyses/{id}	no	1件のリファレンス分析を返します。状態はqueued、analyzing、reference_profileまたはdataとwarningsを含むsucceeded、またはエラーを含むfailedです。無料です。
POST /v1/creator-profiles/quote	no	このリンクのクリエイタープロファイルの料金を見積もります。20クレジット、または過去1時間以内に同じクリエイターのプロファイルがあり、その結果を返せる場合は0です。課金されません。
POST /v1/creator-profiles	yes	InstagramまたはTikTokのプロフィールリンク、または動画リンクのクリエイターの分析を開始します。最新の動画12件について、再生数、いいね数、コメント数、シェア数、再生数の中央値、および各動画の再生数が中央値の何倍かを取得します。結果はすぐに返されます。同じクリエイターを1時間以内に指定すると、同じプロファイルが無料で返されます。20クレジットを確保し、成功時に一度だけ課金されます。非公開または投稿のないアカウントの場合、あるいは失敗した場合は課金されません。1時間あたり新規プロファイルは30件までです。
GET /v1/creator-profiles/{id}	no	1件のクリエイタープロファイルを返します。状態はqueued、analyzing、プロファイルとwarningsを含むsucceeded、またはエラーを含むfailedです。無料です。
DELETE /v1/creator-profiles/{id}	no	完了したクリエイタープロファイルをすぐに削除します。作成時のrunとその課金はそのまま残ります。作成中はrun_not_finishedで拒否されます。無料です。
POST /v1/trend-searches/quote	no	トピック検索の料金を見積もります。20クレジット、または過去1時間以内に同じqueryの検索があり、その結果を返せる場合、もしくはアカウントの月10回の無料検索のいずれかが適用される場合は0です。残りの無料検索回数はfree_searches_leftで示されます。search_idとpageを指定すると、次のページの料金を見積もります。検索から24時間以内は無料です。課金されません。
POST /v1/trend-searches	yes	トピックに関するリールの検索を開始します。platformを指定しない場合、TikTokとInstagramをまとめて順位付けします。各プラットフォームから最大10件、クリエイターごとに1件を取得し、それぞれの再生数をそのクリエイターの中央値と比較します。結果はすぐに返されます。同じqueryを1時間以内に指定すると、同じ検索結果が無料で返されます。20クレジットを確保し、成功時に一度だけ課金されます。片方のプラットフォームの結果しか得られなかった場合も対象です（もう片方はwarnings[]に記載されます）。リールが見つからなかった場合、または失敗した場合は課金されません。毎月最初の10件の検索は、クレジットの確保も課金もありません。失敗した検索は件数に含まれません。1時間あたり新規検索は10件までです。search_idとpageのみを指定すると、完了済み検索の次のページ（next_page）の取得を開始します。検索から24時間以内に、前のページに表示されていないクリエイターを各プラットフォームから最大10件、最大5ページまで取得できます。無料です。同じページを再度指定すると同じ結果が返されます。開始できないページは、クレジットを確保する前にtrend_page_unavailable (409)で拒否されます。ページ取得も同じ1時間あたりの上限に含まれます。
GET /v1/trend-searches/{id}	no	1件のトピック検索を返します。状態はqueued、searching、リールとwarningsを含むsucceeded、またはエラーを含むfailedです。sortを指定すると、同じリールを別の順序で取得できます。無料です。
GET /v1/trend-niches	no	アカウントに保存されたニッチを、primaryを先頭にして取得します。無料です。
POST /v1/trend-niches	no	アカウントのニッチを最大3件保存し、保存済みリストを置き換えます。先頭がprimaryです。keywordsを指定しないtrend searchでは、このニッチが検索対象になります。無料です。
POST /v1/feedback	no	不足している点、わかりにくい点、誤り、遅い点についてフィードバックを送信します。任意で、このアカウントのrunについても報告できます。すべてのフィードバックを確認します。無料です。kind、text、runが同じフィードバックを24時間以内に送信すると、同じfeedback_idが返されます。1時間あたり20件までです。
任意のスキルの実行状況は、同じ場所 GET /v1/runs/{id} から読み取れ、次の状態を遷移します: queued、generating、scripting、tts、avatar、compositing、uploading、succeeded、failed。

GET /v1/runs/{id}?wait_seconds=N（最大50）は、実行が成功または失敗するまで、待機時間が終了するまで、または接続が切れるまで応答を保留するため、読み取りの間にスリープする必要はありません。未完了の実行は現在の状態を返します。

MCPサーバーはこれらのエンドポイントをツールとして提供します。トピック検索は quote_trends と find_trends です。https://clipwright.io/mcp にはすべてのツールが一覧表示されます。クライアントの一覧がこれより短い場合は、古い一覧を保持しています。クライアントの設定でアプリを更新し、新しいチャットを開始してください。

07

スキルとその入力

make_ugc。リップシンク付きUGC動画の生成を開始します。アクターは actor_id（list_actors で保存したアクター）または image から選択され、それ以外の場合はデフォルトのアクターが使用されます。形式と解像度はリクエストとソースに従い、デフォルトは720x1280です。字幕はオプトインです。まずユーザーに確認してください。レンダラーがまだ対応していないフィールドの説明には NOT HONORED YET と記載されています。

run_id がすぐに返されます。poll.arguments を指定して get_run をポーリングし、'succeeded'（video_url）または 'failed' になるまで確認してください。動画の作成がまだ進行中の 'failed' 実行は、後で 'queued' に戻って成功することがあり、その場合は warnings[] に記載されます。attempt=2,3,… は同じ入力で新しい実行を開始します。参考リールのような動画を作成するには、analyze_reference を使用し、その後 plan_reference_remake にその analysis_id を渡してください。

Field	Required	What it means
script	optional	俳優が話す言葉。segments が話す内容を指定しない場合は必須です。segments とテキストにアンカーされた挿入には、サーバー側での長尺コンテンツ利用資格が必要です。音声モデルごとの script の上限：eleven_v3：5000 文字、eleven_flash_v2_5：10000 文字、eleven_turbo_v2_5：10000 文字、eleven_v4：5000 文字、gemini-3.8-flash-tts：5000 文字。スペース、音声タグ、強勢記号も文字数に含まれます。絵文字は2文字として数えられる場合があります。break タグは eleven_v4 と gemini-3.8-flash-tts に送信されるテキストから除かれ、文字数にも含まれません。単語数の上限はありません。長さと料金は、測定するまでは推定値です。ロシア語の強勢：強勢のある母音は、小文字の単語内で大文字にして記述します（「потОм」、「зАмок」）。eleven_v4 と gemini-3.8-flash-tts には、強勢記号 U+0301（「пото́м」）として渡されます。直接入力した記号はそのまま保持されます。単語の先頭の大文字はそのまま大文字として扱われます。また、2つ目の大文字や単語内の大文字の子音を含む単語（すべて大文字、「ВУЗы」など）は変更されません。単語内の大文字の母音が1つだけの場合は、常に強勢として読まれるため、「Яндекс Еда」と記述し、「ЯндексЕда」とは書かないでください。ロシア語で書くユーザーには、この方法で強勢を示せることを伝えてください。eleven_flash_v2_5 と eleven_turbo_v2_5 は低価格ですが、強勢記号を誤読します。大文字は変更されずにこれらのモデルに渡されます。
segments	optional	俳優と画像の順序付きセグメント。サーバー側での長尺コンテンツ利用資格と captions=false が必要です。画像メディアには broll_policy=anyone の明示的な指定が必要です。
inserts	optional	ナレーション全体に重ねる、テキストにアンカーされた画像または動画の挿入。各挿入は、アンカー位置から cover_words 個の発話単語をカバーします。サーバー側での長尺コンテンツ利用資格と broll_policy=anyone の明示的な指定が必要です。字幕は挿入の上に表示されます。
overlays	optional	表示中のプレゼンターに重ねる、テキストにアンカーされた画像または動画。各項目は1つの位置または場所に表示されます。同時に画面に表示できるのは最大2つで、ボックス同士は重なりません。字幕はオーバーレイを避けて中央または下部の3分の1に移動し、顔には重なりません。どちらにも空きがない場合、字幕は非表示になります。全画面の挿入の下では非表示になります。inserts と同じ要件が適用されます：script、サーバー側での長尺コンテンツ利用資格、broll_policy=anyone の明示的な指定。プレゼンターは画面に表示されたままなので、料金は変わりません。
layout_windows	optional	プレゼンターのテキストにアンカーされたリフレーミング：split（9:16 のみ）または card。ウィンドウ同士、または挿入と重ねることはできません。inserts と同じ要件が適用されます。プレゼンターが隠れている、またはぼかされている場合も、ベンダーの作業として納品され、顔の表示時間として請求されます。
framing	optional	テキストにアンカーされたプレゼンターのサイズ指定。各項目は、その単語の間だけ close または medium に切り替わり、終了時に元のテイクに戻ります。項目同士、挿入、またはレイアウトウィンドウと重ねることはできません。全画面テンプレートの下に完全に隠れる framing は warnings[] に記載されます。punch_in の強調と framing が重なる場合は、framing が描画されます。script とサーバー側での長尺コンテンツ利用資格が必要です。料金は変わりません。
templates	optional	グラフィックテンプレート。各要素は { id, kind, anchor, cover_words?, placement?, transition?, data }。スクリプトの実行ごとに適用されます。テンプレートによって料金が変わることはありません。実行ごとの料金は list_prices に記載された各要素に基づいて請求され、テンプレートがカバーするプレゼンターの時間もプレゼンター時間として扱われます。IDは inserts、overlays、layout_windows、templates の間で一意です。テキストは1行で、ラテン文字またはスクリプト固有の文字、数字、一般的な句読点を使用し、絵文字は使えません。幅の広いCJK文字は上限に対して2文字分として数えられ、長いテキストは種類ごとの幅に収まるよう縮小されます。size small|medium|large は種類のサイズを調整します。指定がない場合は medium です。media フィールドには、指定された種類の準備完了アセットの { asset_id } を指定します。内側の引用は、テンプレート自身のテキスト内にある語句を指定します。直前の引用の後に続く語句を指定し、そのビートはその語句の最初の単語に合わせられます。insert または全画面テンプレートの下に配置することはできません。指定がないクリックやステップは均等に配置されます。テンプレートが表示される前に発話されるビートは、表示直後に移動され、警告が出ます。キャプション帯に重なるテンプレートは、表示中にキャプションを隠します。それ以外の場所にあるテンプレート（上部の小さなテンプレートなど）はキャプションを隠しません。全画面テンプレートは表示中、プレゼンター、オーバーレイ、プレゼンター上のテンプレートも隠します。ワイプまたはズームのinsertとは重ねられず、カバーされるプレゼンターの料金は請求されます。同時に表示できるオーバーレイとプレゼンター上のテンプレートは最大3つで、配置領域は重なってはいけません。template_theme はすべてのテンプレートの見た目を設定します。種類: tag (over): プレゼンターまたはinsert上に表示する短いグラデーションのピル。位置の指定がない場合はキャプション位置に表示され、表示中はキャプションを隠します。data text ≤ 32、position? top|center|bottom、size? small|medium|large。lower_third (over): フレーム下部に表示する名前と役職のバー。表示中はキャプションを隠します。style の指定がない場合は clean_bar。data name ≤ 28、role? ≤ 36、side left|right、style? clean_bar|side_rule|soft_pill|mask_reveal、size? small|medium|large。end_card (over): キャプション位置に表示する、任意の行動喚起付きサイトピル。表示中はキャプションを隠します。data site ≤ 32、cta? ≤ 48、size? small|medium|large。title_card (full): 全画面のフックカード。白いカードに最大2行のタイトルを表示し、その横に任意のロゴ画像を配置します。下部には任意のチップを表示できます。data title ≤ 48、chip? ≤ 32、logo? {asset_id} image、size? small|medium|large。quote (full): 全画面の引用カード。引用符、最大4行のテキスト、続いて著者を表示し、任意の丸い写真は円形に切り抜かれます。data text ≤ 120、author? ≤ 32、photo? {asset_id} image (円形に切り抜いて表示)、size? small|medium|large。stat (full|over): 0からvalueまでカウントアップする数値（小数点以下最大2桁）。前後にprefixとsuffixを付け、その下にラベルを表示します。full はフレーム全体を使い、over は胸の高さにカードとして表示します。data value number、prefix? ≤ 6、suffix? ≤ 6、label? ≤ 32、size? small|medium|large。callout (over): フレーム上の点を指して脈動する矢印またはリング。target {x,y} はフレーム左上からの割合で指定し、その下または上に任意のラベルピルを表示できます。顔を指すこともできますが、可能な限りラベルは顔を避けます。insert上にも表示できます。data target {x,y}、style arrow|ring、text? ≤ 24、size? small|medium|large。checklist (over): 2～4行で、各行に任意のアイコン、ラベル、オンまたはオフに設定されたスイッチかチェックボックスを表示します。カーソルが行を順にクリックします（item は行の0始まりのインデックス）。クリックするたびに状態が切り替わります。顔の下に表示します。data items 2–4 of {label ≤ 24, on true|false, icon? phone|briefcase|user|clock|chat|star}、clicks? 0–6 of {item number, quote? inner quote}、style? switch|check、size? small|medium|large。phone_call (over): 画面端に表示する、ニュートラルな電話の着信画面（side が left でない場合は右側）。発信者、字幕、丸いアバターリングを表示し、answer_at で応答するとタイマーが動きます（または保留バナーを表示）。横長フレームでは顔の横、縦長フレームでは顔の下に表示します。data caller ≤ 24、subtitle? ≤ 32、avatar? {asset_id} image (円形に切り抜いて表示)、answer_at inner quote、side? left|right、size? small|medium|large、banner? ≤ 32、banner_note? ≤ 48、mask_number? true|false。compare (full): 全画面の3:5カードに変更前の画像を表示します。reveal_at で変更後の画像が斜めにスイープして表示されます（reveal の指定がない場合）。または左から中央の仕切りまでワイプして表示され、両方の画像が残ります。wipe_full は変更後の画像がカード全体を覆うまでワイプします。任意のラベルピルを表示できます。data before {asset_id} image (全体に合わせて切り抜き)、after {asset_id} image (全体に合わせて切り抜き)、labels? {before? ≤ 20, after? ≤ 20}、reveal_at inner quote、reveal? sweep|wipe|wipe_full、size? small|medium|large。notification (over): 顔の上部に表示する電話通知。アイコン（指定がなければアプリの頭文字）、アプリ名、タイトル、本文1行を表示します。通知はスライドインし、少なくとも1.2秒間表示された後、表示時間の終了前に消えます。スタック内の各カードは指定された at で上に重なるようにスライドインし、それ以前のカードを後ろに押し戻します。data app ≤ 20、title ≤ 32、body ≤ 80、icon? phone|briefcase|user|clock|chat|star、stack? 1–2 of {app? ≤ 20, title ≤ 32, body ≤ 80, icon? phone|briefcase|user|clock|chat|star, at? inner quote}、size? small|medium|large。progress (over): カード上に縦並びで2～5個のステップを表示し、advance_at の引用（各ステップにつき1つ、順番どおり）に合わせて、または均等に、順にチェックを付けて完了します。顔の下に表示します。data steps 2–5 of ≤ 20、advance_at? 2–5 of inner quote、size? small|medium|large。rating (over): カード上に5つの星を表示し、stars の数（1～5、0.5刻み。半分の星は半分だけ塗りつぶし）まで順に塗りつぶします。星の下に任意のラベルを表示できます。胸の高さに表示します。data stars number、label? ≤ 32、size? small|medium|large。chat_window (full): 全画面のチャットウィンドウ。プロンプトが入力され、回答が単語ごとに表示され、表が行ごとに開き、その後、返信カードが表示されます。それぞれ指定された at に合わせるか、均等に配置します。zoom true の場合、ビートに合わせてズームイン・ズームアウトします。data app? ≤ 24、prompt ≤ 120、replies? 1–3 of {title ≤ 32, body? ≤ 64, at? inner quote}、answer? {text ≤ 150, at? inner quote}、table? {columns 2–3 of ≤ 16, rows 1–4 of {cells 2–3 of ≤ 20, at? inner quote}}、zoom? true|false、size? small|medium|large。video_grid (full): アカウントの動画アセットを9:16のタイルで表示する全画面グリッド。2x2（セル1～4、左列を高く配置）または3x1（セル1～3）です。layout の指定がない場合は、指定されたセルに応じてレイアウトが決まり、各タイルは1つ前のタイルの後に表示され、ミュートで再生されます。上部に任意のタイトルを表示できます。data layout? 2x2|3x1、cell_1 {asset_id} video (全体に合わせて切り抜き)、cell_2 {asset_id} video (全体に合わせて切り抜き)、cell_3 {asset_id} video (全体に合わせて切り抜き)、cell_4? {asset_id} video (全体に合わせて切り抜き)、title? ≤ 40、size? small|medium|large。word_title (full): アクセントカラーで表示する全画面のキネティックタイトル。最初の項目はテンプレートの最初のフレームから表示され、以降の項目は指定された at の引用（通常は発話された同じ語句）に合わせて表示されます。指定がない場合は均等に配置されます。reveal replace（デフォルト）は一度に1項目を表示し、build はタイトルに項目を追加していきます。data words 1–8 of {text ≤ 16, at? inner quote}、reveal? replace|build、size? small|medium|large。phone_screen (full): 全画面の電話画面で画面動画を再生します（ミュート。動画がない場合はグラデーション）。状態は順に切り替わり、それぞれ指定された at の引用に合わせるか、均等に配置されます。lock（暗く表示し、ロックとテキストを表示）、play（動画を鮮明に表示し、画面上部にテキストを表示）、liked（ハートとテキストを表示）、counter（画面下部にピルを表示）、timer（画面上端にバッジを表示）、tag（画面脇にポインター線付きのチップを表示）。lock、play、liked は互いに置き換わり、tag は追加され、後から表示される counter または timer はそれ以前のものを置き換えます。data screen? {asset_id} video (全体に合わせて切り抜き)、states 1–6 of {state lock|play|liked|counter|timer|tag, text? ≤ 24, at? inner quote}、size? small|medium|large。terminal (full): 全画面の暗いターミナルカード。コマンドが入力され、その下のdiffでは diff.at に合わせて削除行（赤）が折りたたまれ、追加行（緑）が開きます。その後、at に合わせてチェック付きのステータス行が表示されます。title はカードの名前です。data title? ≤ 24、command ≤ 100、diff? {lines 2–7 of {text ≤ 36, change? add|del}, at? inner quote}、status ≤ 40、at? inner quote、size? small|medium|large。pointer_chips (over): 顔の下に縦並びで1～4個のチップを表示します（side が left でない場合は右側）。各チップは、フレーム左上からの割合で指定する target {x,y} の点に曲線でつながり、指定された at の引用に合わせて、または均等に順に表示されます。線は顔の上を通ることがありますが、チップは顔に重ならないように配置されます。insert上にも表示できます。data items 1–4 of {target {x,y}, text ≤ 20, at? inner quote}、side? left|right、size? small|medium|large。chart (full): カード上に2～6個のラベル付きデータ点を表示する全画面の棒グラフまたは折れ線グラフ。各点の at に合わせて、または均等に、棒が伸びるか線がその点まで描かれ、値がカウントアップします。値の後にsuffixを表示し、上部にタイトルを表示します。data type bar|line、title? ≤ 40、suffix? ≤ 6、points 2–6 of {label ≤ 12, value number, at? inner quote}、size? small|medium|large。race (full): 全画面の順位付き棒グラフレース。名前ごとに棒を1本表示し、最も長い棒を上に配置します。最初のラウンドの値は開始時から表示され、その後は各ラウンドの at に合わせて、または均等に、棒がそのラウンドの値に移動し、順位に応じて並び替わります。ラウンドのラベルは棒の下に表示されます。data title? ≤ 40、suffix? ≤ 6、names 3–6 of ≤ 14、rounds 2–5 of {label? ≤ 10, values 3–6 of number, at? inner quote}、size? small|medium|large。hand_title (full|over): 手書き風フォントで、最大2行のタイトルを一画ずつ描きます。その後、mark.at に合わせて、またはテンプレートの後半に、mark.word（0始まりのインデックス）から mark.words（指定がない場合は1）個の単語にマーカーを引きます。over はキャプション位置に表示され、キャプションを隠します。data text ≤ 40、mark? {word number, words? number, style highlight|underline|circle, at? inner quote}、size? small|medium|large。word_fill (full): 動画（clip、ミュートで再生）を文字の中に表示する、全画面の巨大な単語。フレームの残りの部分にはテーマの背景色を使います。最初の10フレームで拡大します。data word ≤ 10、clip {asset_id} video、size? small|medium|large。
template_theme	optional	実行内のすべてのテンプレートの見た目。プリセットと任意のアクセントを指定します。templates がある場合のみ使用できます。
design	optional	実行のデザインDNA。テンプレート、エンドカード、キャプションのアクセントに適用されます。ブランドを指定するか、extract_brand を使用します。指定がない場合は保存済みのブランドキットを使用します。template_theme とは併用できません。
template_sounds	optional	受け付けられます。スキーマにはまだ説明がありません。
scenes	optional	テンプレートでは表現できない内容のために、動画用にあなたの言葉から作成するグラフィック。各グラフィックは、言葉が話されている間、プレゼンター上（over）または全画面（full）に描画されます。キャプションに重なるグラフィックは、表示中にキャプションを隠します。チェックに通らないものは除外され、warnings[] に記載されます。1シーンあたり25クレジット。引用行は個別に記載され、納品動画に描画されたシーンに限り請求されます。サーバー側で script と long-form の条件を満たす必要があります。
motion_style	optional	受け付ける型: object。
moves	optional	list_moves にある動きを、あなたの言葉に合わせて適用します。各要素は { name, anchor: { quote }, cover_words?, placement?, data? }。それぞれ list_moves の説明どおりに描画され、data には指定されたフィールドを設定します。指定された言葉に合わせて、またはこの動画内で描画できない動きは warnings[] に記載されて除外されます。黙って削除されることはありません。クレジットは引用に対して請求されます。
edit_sounds	optional	受け付ける値: true | false。
music	optional	動画用に作成される、音声の下に流すBGM。指定がない場合はオフです。"auto" はスクリプトからムードを判断します。{ mood } は、たとえば "calm lo-fi" のように、あなたの言葉でムードを指定します。動画1本あたり60クレジット。引用には個別の行として記載され、音楽付きで動画が納品された場合に限り請求されます。
call	optional	引用の後に続く電話通話。プレゼンターが聞き、その後、電話回線の音声で通話が再生されている間は静止します。最初に呼び出し音が鳴り、横には通話中の電話が表示されます（通話をカバーする phone_call テンプレートがある場合は、代わりにそれを使用します）。script、9:16のフレーム、通話後の言葉が必要です。静止したプレゼンターと通話によって制作秒数が加算されますが、プレゼンター秒数は加算されません。通話中に表示されるライブアバターには、list_prices に記載された個別料金がかかります。サーバー側で long-form の条件を満たす必要があります。
interview	optional	インタビュー：画面外の話者が台本の指定された言葉を自分の声で話し、プレゼンターは残りを画面上で答え、画面外の話者が話している間は静止します。サーバーで台本と長尺動画の利用資格が必要です。プレゼンターの静止フレームは制作秒数に加算されますが、プレゼンター秒数には加算されません。
presenter_gaze	optional	視聴者から見た、指定された言葉を話すときのプレゼンターの視線の向き：カメラ、左、右。その向きの actor_id（list_actors）が必要です。視線の変更はカットになります。
shots	optional	台本の一部の言葉に合わせた、俳優のライブショット：talking（話す）、talking_action（演技しながら話す）、action（言葉がナレーションとして流れる間に演技する）。ショットは重ねられません。ショット以外の言葉は通常のプレゼンター撮影になります。サーバーで9:16フレームと長尺動画の利用資格が必要です。各種類のプレゼンター秒単価は list_prices に記載されています。
product_asset_id	optional	商品を映すショットで表示する商品画像（ast_…）。
scene	optional	動画全体で使う1つのシーンを一度だけ記述します。場所、プレゼンターの立ち方や座り方、服装、商品の見た目、小道具、照明を指定します。動画内のプレゼンターとすべてのライブショットはこのシーンに描画されます。自分で用意したプレゼンター写真（image）はそのまま保持されます。省略すると、台本とプレゼンターの画像からシーンが作成されます。無料です。
proposal	optional	受け付ける型：object。
propose	optional	quote_ugc 専用：false にするとシーンの提案を求めません。省略した場合、シーンのない quote にはシーンが提案されます。無料です。
person	optional	まだ対応していません：person はまだ対応していません。このリクエストではデフォルトの俳優が使われます。別の顔を選ぶには、list_actors から actor_id を選ぶか、image を指定してください
actor_id	optional	list_actors から取得した保存済み Clipwright 俳優 ID。actor_id、image、person のいずれかを選択してください。組み合わせて指定することはできません。voice または voice_id を指定しない場合、声は俳優の性別に応じて選ばれます。actor_gender とは併用できません。
presenter_framing	optional	close（デフォルト）、wide（プレゼンターを低めに配置し、上部に部屋を映す）、full（頭から足まで）。list_actors にある、その名前の俳優の視点が必要です。9:16 のみ対応。full が使えない場合は wide、次に close に切り替わり、warnings[] が追加されます。
presenter_mic	optional	true：プレゼンターが小型マイクを持ちます。list_actors にある、そのフレーミングでの俳優のマイク視点が必要です（ライブラリの俳優は wide のみ）。利用できない場合はマイクなしとなり、warnings[] が追加されます。
image	optional	俳優の写真を指定する公開 https URL（PNG、JPEG、WebP、最大 10 MB）。ディスク上のファイルは、まず upload_image（POST /v1/uploads）でアップロードし、返された URL を渡してください。使用できないソース（非公開ホストまたはループバックホスト、http、到達不能、リダイレクトあり、10 MB 超過、または指定された画像形式以外）は、課金前に拒否されます（unusable_source）。顔の性別は検出しません。actor_gender または voice を指定してください。指定しない場合は、警告とともにデフォルトの男性の声が使われます。
actor_gender	optional	female | male。image を指定しない場合、その性別のカタログ俳優（female：actor_anna、male：actor_alex）が actor_id を指定した場合と同様に選ばれ、warnings[] に名前が記載されます。ほかの俳優は list_actors で確認できます。image を指定した場合は、画像内の顔の性別を表し、その性別のデフォルトの声（female：sarah、male：george。gemini-3.8-flash-tts の場合は kore と charon）が選ばれます。actor_id（性別が既知）および person とは併用できません。明示的に指定した voice または voice_id は、ここで選ばれる声より優先され、警告が表示されます。
name	optional	まだ対応していません：name はまだ対応していません。レンダラーには渡されません
broll_policy	optional	Bロールのポリシー：anyone は俳優を含む人物を許可します。no_actor は俳優を除外します。no_people は手を含むすべての人物を除外します。独自の画像または動画を使うテンプレートには "anyone" が必要です。それ以外の場合は保存のみです。実行時の指定はアカウントの俳優デフォルトより優先されます。どちらも指定されていない場合は no_people になります。
captions	optional	単語ごとのタイミングに合わせた字幕を動画に焼き込みます。プレゼンターと挿入映像の上に表示されます。segments とは併用できません。
caption_style	optional	captions=true の場合の字幕の見た目。hormozi：デフォルト。太い黒の縁取りがある白の太字大文字。1つの字幕キューにつき最大3語、キーワード1語を黄色で表示（emphasised があればその語、なければストップワード以外で最も長い語）。accent：縁取りなしの白の太字大文字で、幅の狭い書体。1つの字幕キューにつき最大3語、キーワード1語をオレンジ色で表示（emphasised があればその語、なければストップワード以外で最も長い語）。tiktok：丸みのある太字大文字で、一度に1語または2語。話された語が黄色に変わり、大きくなります。youtube：画面下部近くの暗い角丸ボックスに、読みやすい太字サンセリフ体で4語（16:9 では5語）を表示。語がフェードインし、話された語は赤になります。instagram：ピンクの縁取りがあるコミック調の大文字で、一度に2語。話された語がオレンジ色で弾けるように表示されます。minimalist：半透明の暗い帯に、シンプルなサンセリフ体で4語を表示。穏やかにフェードします。neon：マゼンタの縁取りがあるシアンの大文字で、一度に2語。話された語が白く弾けるように表示されます。genz：大きなコミック調の大文字で、一度に1語。ピンクのハイライトとともに勢いよく表示されます。campfire：丸みのあるコミック調の大文字で3語。話された語が金色に光り、そのまま点灯します。midnight：不気味な雰囲気の大文字で2語、ゆっくりフェードします。話された語は赤になります。plottwist：太字サンセリフ体で3語。話された語が空色に変わり、大きくなります。headline：黒一色の帯に、縦長の大文字で3語。話された語が黄色で拡大します。promo：青いピル型の背景に太字サンセリフ体で3語。話された語が黄色で弾けるように表示されます。lecture：暗い角丸ボックスに、読みやすいサンセリフ体で4語。話された語は緑になります。highlighter：太字サンセリフ体で4語。話された語がライム色に変わり、そのまま点灯します。studio：ぼかした暗いボックスに、サンセリフ体で4語をタイプ入力するように表示。話された語は琥珀色になります。broadcast：画面下部に、縁取りのあるサンセリフ体で4語。話された語は淡い黄色になります。arcade：ブロック状の黄色い大文字で2語。話された語が白く弾むように表示されます。clutch：筆文字風の大文字で、一度に1語。緑色で勢いよく表示されます。bubblegum：ピンクの縁取りがある丸みを帯びたディスプレイ書体で2語。話された語が黄色で弾みます。crayon：紺色の縁取りがあるマーカー手書き風で2語。話された語がオレンジ色で弾けるように表示されます。lyrics：手書き風の筆記体で4語。話された語がピンクに光り、そのまま点灯します。bassdrop：縁取りのあるディスプレイ書体の大文字で、一度に1語。オレンジ色で拡大しながら表示されます。punch：画面中央に導入とパンチラインを表示。小さな白い導入文の上に、青く光る大きなキーワードを1語または2語表示します。ほかの語は小さな白字です。別名：minimal は minimalist を描画します。台本の文字を描画できないフォントは、標準的なサンセリフ体に置き換えられます。プレビュー：https://clipwright.io/captions
caption_emphasis	optional	強調するキーワードまたは短いフレーズ。各項目は台本から引用し、挿入映像の引用と同じ方法で照合されます（大文字・小文字と句読点は無視）。項目には引用文そのもの、または { quote, look } を指定します。look punch は同じ文の短い導入文の下に、引用文を大きく光るキーワードとして表示します。look pill は引用文だけを角丸のピル型背景に表示します。look color は同じサイズのままアクセントカラーで表示します。look box は同じサイズのままアクセントカラーの柔らかなボックス上に表示します。look を指定しない場合、punch は punch として描画され、hormozi と accent は color として描画され、ほかのプリセットでは引用文がハイライトカラーで大きく表示されます。該当するすべての箇所が強調されます。captions=true と script が必要です。台本にない引用文は課金前に拒否されます。
caption_mode	optional	full（省略時のデフォルト）：話されたすべての語に字幕を付けます。highlights：caption_emphasis の引用文の周辺（導入、引用文、短い続き）にのみ字幕を表示し、それ以外には表示しません。caption_emphasis が必要です。どちらのモードでも、全画面の挿入映像が表示されている間、またはテンプレートが字幕帯に重なる間は字幕が非表示になります。
caption_position	optional	字幕の位置：top、middle、lower、bottom（高さの80%）。省略すると caption_style 固有の位置になります。captions=true が必要です。
caption_place	optional	caption_position の代わりに、字幕を指定した高さに固定します。オーバーレイによって字幕が移動することはありません。字幕に重なるオーバーレイは、relative_to captions に配置されていない限り拒否されます。captions=true が必要です。
presenter_place	optional	フレーム内でのプレゼンターの顔の高さと中央位置。指定位置に合わせてポートレートを拡大し、close の視点では近すぎる場合は俳優の wide の視点を使います。それでも近すぎる場合は、描画された顔の高さが warnings[] に記載されます。オーバーレイ、挿入映像、layout_windows、framing、call を含む actor_id と script が必要です。料金は変わりません。
look	optional	まだ対応していません：look はまだ対応していません。レンダラーには渡されません
aspect_ratio	optional	出力形式：9:16 | 1:1 | 16:9。image を指定しない場合は 9:16 です。image を指定した場合は、横長の画像も含め、画像の形状に最も近い対応形式になります。image を指定する場合は、必ず明示してください。リクエストとソースの差が15%を超える場合、課金前に拒否されます（aspect_conflict）。
resolution	optional	出力解像度：720p | 1080p（短辺が720 / 1080 px）。省略すると 720p になります。
voice	optional	list_voices にある音声名。厳選プリセット：sarah | george | eric | daria_ru_female。list_voices が返さない名前は、課金前に API によって拒否されます。省略すると、俳優の性別に応じたデフォルトの声になります。性別は actor_id または actor_gender で決まり、デフォルトの俳優および actor_gender を指定していない image では george が使われます。gemini-3.8-flash-tts は独自の音声（list_voices の kind model_voice。例：kore）のみを話します。その音声を指定すると、そのモデルが選択されます。指定した音声を話せない tts_model との組み合わせは、課金前に拒否されます。voice_id とは併用できません。
voice_id	optional	カタログ外の音声に使う、ベンダーの生の音声 ID（英数字16～32文字）。遅延チェックされるため、未知の ID はリクエストではなく実行時に失敗します。tts_model=gemini-3.8-flash-tts との組み合わせは拒否されます。voice とは併用できません。
tts_model	optional	音声モデル：eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5 | eleven_v4 | gemini-3.8-flash-tts。省略すると、選択した音声のモデルが使われます（list_voices に表示）。独自の音声には gemini-3.8-flash-tts、すべてのプリセット、カタログ音声、生の voice_id には eleven_v4 が使われます。明示的に指定した tts_model が優先されます。ただし eleven_v3 は現在読み上げに使われません。これを指定した実行では、警告とともに eleven_v4 で読み上げられます。eleven_v4 と gemini-3.8-flash-tts は強勢記号を読み取ります（ロシア語の単語内の大文字母音「потОм」は1つの語として扱われます。script を参照）。eleven_flash_v2_5 と eleven_turbo_v2_5 は、ロシア語以外の言語向けの低価格な代替モデルです。gemini-3.8-flash-tts は独自の音声のみを話します（model=gemini-3.8-flash-tts を指定した list_voices。voice を指定しない場合、女性の俳優には kore、それ以外には charon）。単語ごとのタイミング情報を返さないため、プリセット音声、カタログ音声、voice_id、captions=true、segments、挿入映像との組み合わせは、課金前に拒否されます。角括弧内の音声タグはほかの音声モデルで使う慣例であり、このモデルでは測定されません。音声モデルごとの台本の上限：eleven_v3：5000文字、eleven_flash_v2_5：10000文字、eleven_turbo_v2_5：10000文字、eleven_v4：5000文字、gemini-3.8-flash-tts：5000文字。空白、音声タグ、強勢記号も文字数に含まれます。絵文字は2文字として数えられる場合があります。break タグは eleven_v4 と gemini-3.8-flash-tts に送信するテキストから削除され、文字数にも含まれません。単語数の上限はありません。長さと料金は測定されるまで推定値です。
voice_pace	optional	ナレーションの速度。1 は音声本来の速度です。gemini-3.8-flash-tts では代わりにスタイルのヒントが使われます。eleven_v4 には速度設定がないため、list_voices の words_per_second を参考に音声を選んでください。どちらも warnings[] に記載されます。
pause_trim	optional	この秒数を超える間をカットします。false の場合はすべて保持します。テンプレート、シーン、ショットでのデフォルト：文間は0.15秒、コンマの後は0.08秒。
end_hold_s	optional	最後の言葉の後に最終フレームを表示し続ける秒数。プレゼンターは静止し、画面上のすべてのレイヤーもそのまま表示されます。制作秒数に加算されますが、プレゼンター秒数には加算されません。script と長尺動画の利用資格が必要です。
visible_ai_label	任意	新たにマークされるプレゼンター動画（長尺を含む）に表示するAIラベル。デフォルトではサーバーの admission policy で true に設定されています。False にすると表示ラベルのみが非表示になり、不可視のマーキングや署名付き provenance は無効になりません。過去の出力は変更されません。
background	任意	使用できる値: white | blur | contain。
max_credits	任意	この呼び出しで消費できるクレジットの上限。測定コストが上限を超えても、実行で請求される額は上限を超えません。実行に必要な reserve が上限を超える場合、何も reserve または開始される前に max_credits_exceeded で呼び出しが拒否され、請求も発生しません。上限以下の場合は通常どおり実行されます。
create_actor. このアカウント用のパーソナルアクターを、架空の成人を描写する言葉から作成します。顔がちょうど1つ写った9:16のポートレートと、そこから編集した、リクエストされたその他の形式を作成します。すぐにrun_idを返します。'succeeded'（created_actor.actor_id。これをactor_idとしてmake_ugcに渡します）または'failed'になるまでget_runをポーリングしてください。公開された画像1枚ごとに、見積もりに表示された料金が請求されます。拒否された描写と使用できないポートレートには料金がかかりません。生成がオフになっている場合、呼び出しはactor_generation_disabledで失敗します。from_actor_idを指定すると、顔は維持されます（照合されます。不一致の場合、料金はかかりません）。style_referenceを指定した場合、写真の人物に似たポートレートは無料で拒否され、料金は同じです。portrait（genderとapproximate_ageを指定）は無料で9:16のポートレートになり、料金がかかるのはその他の形式のみです。顔がちょうど1つ写っていない画像や、顔が切れている、小さすぎる、または大きすぎる画像は無料で拒否されます。generate_imageで描いたブランドマスコットは、顔が人間の顔（漫画の人物）として認識できる場合、ポートレートにできます。動物や物体のマスコットは拒否されるため、挿入画像で見せてください。

Field	Required	What it means
description	optional	架空の成人を描写する言葉：外見、服装、設定。実在の人物の名前や、その人物に似せる指定は、料金が発生する前に拒否されます（actor_prompt_refused）。from_actor_idまたはportraitを指定しない場合は必須です。from_actor_idを指定した場合は、ビューの外見、服装、ポーズを指定しますが、性別と年齢は元のアクターのものが維持されます。
gender	optional	female | male。アクターの性別と、このアクターを使った動画のデフォルト音声を指定します。from_actor_idを指定しない場合は必須です。
approximate_age	optional	おおよその年齢（年単位）、18～90歳：アクターは成人です。from_actor_idを指定しない場合は必須です。
name	required	list_actorsに表示される名前。
aspect_ratios	optional	作成する形式：9:16 | 1:1 | 16:9。常に9:16を含めてください。省略すると3種類すべてが作成されます。アイデンティティチェックに失敗した形式には料金がかからず、warningsに記載されます。
from_actor_id	optional	このアクター（ライブラリアクターまたは自分のアクター）を元に、新しいパーソナルアクターを作成します。同じ顔、性別、年齢を維持し、framing、holding、setting、description、またはstyle_referenceでビューを変更します。genderとapproximate_ageは省略してください。
framing	optional	ショットサイズ：close（デフォルト、胸から上）、wide（腰から上、手と頭上の余白を含む）、またはfull（立ち姿、頭から足まで）。言葉から作成する場合は、新しいポートレートのフレーミングを指定します。from_actor_idを指定した場合、wideまたはfullではカメラが後ろに下がります。ビューは描画された顔のサイズに基づいて分類され、make_ugcでは同じ名前のpresenter_framingでレンダリングされます。style_referenceまたはportraitとは併用できません。これらの画像がショットを決定します。
holding	optional	プレゼンターが持つオブジェクトを最大2つ指定します。片手に1つずつです。
setting	optional	プレゼンターを配置する部屋や背景を言葉で指定します。
style_reference	optional	新しいポートレートがセット、照明、カメラアングル、ショットサイズ、服装を参考にするPNGまたはJPEG写真：写真に合わせて胸から上、腰から上、または全身。胸から上より広いポートレートはwideビューになります。このアカウントの画像アセット（アップロード、URLインポート、または検索で見つけた画像。rights_confirmedが必要）。from_actor_idを指定しない場合、顔はdescriptionから新たに作成されます。指定した場合は、元のアクターの顔になります。写真の人物に似たポートレートは無料で拒否されます。
portrait	optional	生成ではなく、自分のポートレート画像からアクターを作成します。このアカウントのPNGまたはJPEG画像アセット（rights_confirmedが必要）で、縦横比が9:16から2%以内、顔がちょうど1つ写っており、顔が切れておらず、小さすぎず大きすぎないものを指定します。無料でアクターの9:16ポートレートになり、その他の形式はそこから編集され、通常どおり料金がかかります。genderとapproximate_ageを指定してください。description、style_reference、from_actor_idとは併用できません。
max_credits	optional	この呼び出しで使用できるクレジットの上限：実測コストが上回っても、実行に対してこの上限を超える請求はありません。実行の予約額が上限を超える場合、何も予約または開始される前にmax_credits_exceededで呼び出しが拒否され、料金は発生しません。上限以上の場合は通常どおり実行されます。
quality	optional	画像品質：medium | high。省略するとmediumになります。highでは最も自然なポートレートが生成されます。画像1枚あたりの料金は品質によって異なり、請求前に見積もりに表示されます。

make_faceless. スクリプトまたは概要から、料金が発生する完成済みの顔出しなし動画を作成します。長さは30～90秒から選択します。動画はナレーションの終了に合わせて終わり、最低25秒（解説動画の場合はナレーションと同じ長さ）、選択した長さの最大1.25倍までで、90秒を超えることはありません。動画には冒頭のアニメーションクリップと画像シーンが含まれます。字幕はデフォルトでオンですが、オフにできます。

すぐにrun_idを返します。'succeeded'（video_url）または'failed'になるまで、poll.argumentsを指定してget_runをポーリングしてください。attempt=2,3,…を指定すると、同じ入力で新しい実行が開始されます。

Field	Required	What it means
input_mode	required	'script'は入力したテキストをそのままナレーションにし、'brief'は短い説明からナレーションを作成します。このモードに一致するscriptまたはbriefのどちらか一方だけを送信してください。
script	optional	読み上げるナレーション。input_modeが'script'の場合は必須です。'brief'の場合は指定しないでください。
brief	optional	動画の内容。これを元にナレーションが作成されます。input_modeが'brief'の場合は必須です。'script'の場合は指定しないでください。
duration_seconds	required	選択する長さ。30～90秒、1/25秒のフレーム境界に合わせて指定します。動画はナレーションの終了に合わせて終わり、最低25秒（解説動画の場合はナレーションと同じ長さ）、通常は選択した長さの最大1.25倍かつ90秒までです。ナレーションがそれより長い場合は、ナレーションの終了まで動画が続きます。選択した長さより5秒を超えて長い動画はwarnings[]に記載されます。料金が見積もりを超えることはありません。スクリプトは、推定長が21秒から選択した長さ+5秒まで、かつ最大90秒の場合に受け付けられます。
style_reference	optional	シーンがビジュアルスタイルを参考にする、公開されたhttps画像。
character_reference	optional	人物またはキャラクターの画像：公開されたhttps画像、またはアップロード済みかアセットに保存済みの画像。standard形式では、生成するすべての画像と冒頭のクリップにキャラクターが登場します。自分のscene_imagesはそのまま表示されます。explainer形式では、キャラクターが主役になります。character_detailsでフォトリアルな見た目を指定しない限り、人物写真は漫画風に描かれます。
character_details	optional	髪、服装、身に着けていないアクセサリーなど、人物またはキャラクターの固定されたビジュアルの詳細。生成するすべてのシーンで維持されます。
mascot_id	optional	アセットに保存されたマスコット（mascot trueを指定してlist_assetsで取得）。explainer形式では、すでに描画済みの主役として使われ、ポーズ画像は作成も課金もされません。character_referenceとcharacter_detailsの代わりに使用します。
scene_images	optional	ナレーションの単語範囲または引用箇所に配置する自分の画像。無料です。explainer形式では、製品画像を最大3枚まで指定できます。該当する言葉に合わせてそのまま表示され、主役が持つカードとして、または全画面で表示されます。
captions	optional	動画に焼き込む字幕。デフォルトでオンです。
transitions	optional	カットにフラッシュまたはライトリークとその効果音を付けます。各シーンの切り替わり、または各アンカーに最も近い切り替わり（scriptのみ）に適用されます。briefで省略すると、各シーンの切り替わりにフラッシュが適用されます。falseを指定すると通常のカットになります。追加料金はありません。
edit_sounds	optional	各シーンの切り替わりに、ピークがカットに合う小さな効果音を付けます。template_sounds.editで選択します。料金は変わりません。
template_sounds	optional	効果音なしの場合はfalse、またはlist_template_soundsから{ flash, whoosh (light leak), edit: name }を指定します。
music	optional	音声の下に流す、この動画用に作成されたBGM。指定しない限りオフです。"auto"はスクリプトから雰囲気を判断します。{ mood }では、たとえば"calm lo-fi"のように言葉で指定します。動画1本につき60クレジットで、見積もりに別項目として表示され、BGM付きで動画が納品された場合にのみ請求されます。
templates	optional	scriptのみ：make_ugcと同様に、スロットに自分の画像または動画アセットを表示できます（asset_id、rights_confirmed）。無料です。
shots	optional	scriptのみ：{id, anchor, action, asset_id?}を1～10個指定します。各ショットは最大5秒です。
scenes	optional	scriptのみ：make_ugcのscenesと同様です。
motion_style	optional	make_ugcのmotion_styleと同様です。scriptのみで使用できます。無料です。
moves	optional	scriptのみ：自分の言葉に合わせてlist_movesから選ぶ動き。各項目は{ name, anchor: { quote }, cover_words?, placement?, data? }です。それぞれlist_movesに記載されたとおりに描画されます。dataには、指定されたフィールドを設定します。該当する言葉に合わせて描画できない動きや、この動画では使えない動きはwarnings[]に記載され、除外されます。黙って削除されることはありません。料金は見積もりに表示されます。
format	optional	'explainer'：描画された解説漫画。すべての言葉にイベントがあり、主役が画面の隅に表示されます。scriptのみ。1人のナレーターが語る、具体的な行動の連続に適しています。手順を追うハウツー、仕組みの説明、ワークフロー、ツールの使い方、N個の間違いやN通りの方法など、すべてのフレーズに見せるものがある内容です。行動を伴わない推論、会話、人物についての物語には適しません。すべてのスクリプト見積もりでexplainer_fitが返されます。適している場合はこの形式を提案し、適していない場合は理由と、行動を中心にした書き換え案を提示してから確認を求めます。主役には、まずmascot_id、次にブランドのマスコットを使用します。どちらも無料です。それ以外の場合は、指定したキャラクター、またはスクリプトに合うキャラクターを使用し、ポーズ画像9枚が見積もりに各7クレジットで加算されます。ティアごとに1本の動画として料金が設定され、制作には約30分かかります。音声を指定しない場合、英語のスクリプトは最速の音声で読み上げられます。
tier	optional	format explainerのみ。'standard'（デフォルト）：60秒までの動画は700クレジット、60秒を超える場合は1秒ごとに12クレジット追加されます。'pro'：より丁寧な演出と豊かなシーン。60秒までの動画は1200クレジット、60秒を超える場合は1秒ごとに20クレジット追加されます。ポーズ画像の料金は別途加算されます。quote_facelessには両方の合計が表示されます。両方を提示して、ユーザーに選んでもらってください。
pause_trim	optional	scriptのみ：make_ugcのpause_trimと同様です。templates、scenes、shots、またはformat explainerを指定した場合も、同じデフォルト設定が適用されます。
voice	optional	ナレーション音声：skill=make_facelessのlist_voicesにある名前（kind faceless_voice）。省略するとnarrator_en_wise_ladyになります。英語の解説動画では最速の音声が使われます。ナレーションの言語に合った音声を選んでください。どの音声でも任意の言語を読み上げますが、アクセントは音声固有のものになります。未知の名前やmake_ugc用の音声は、料金が発生する前にAPIによって拒否されます。ここではraw voice_idは受け付けられません。
resolution	optional	出力解像度：720p（720x1280）または1080p（1080x1920）。省略すると720pになります。料金は解像度によって変わりません。
max_credits	optional	この呼び出しで使用できるクレジットの上限：実測コストが上回っても、実行に対してこの上限を超える請求はありません。実行の予約額が上限を超える場合、何も予約または開始される前にmax_credits_exceededで呼び出しが拒否され、料金は発生しません。上限以上の場合は通常どおり実行されます。
scene	optional	動画全体に共通するシーンを一度だけ記述します。場所、主役の立ち方や座り方、服装、製品の見た目、小道具、照明を指定します。動画内のすべての画像と動くクリップがこの設定で描画されます。format explainerの場合、動画のシーンはこの設定の中に配置されます。省略すると、画像を使う動画ではストーリーに合わせたシーンが1つ作成されます。無料です。
proposal	optional	受け付ける型：object。
propose	optional	quote_facelessのみ：falseを指定すると、シーンの提案を求めません。省略すると、シーンのない見積もりではシーンが1つ提案されます。無料です。

• 顔出しなし動画には、カメラの前に登場するプレゼンターはいません。冒頭のアニメーションクリップと画像シーンにナレーションが重なります。script と brief のうち、input_mode が指定する一方だけを送信してください。
• duration_seconds は目標値であり、動画をその長さまで引き延ばす値ではありません。動画はナレーションとともに終了します。ナレーションは少なくとも25秒（解説動画の場合はナレーションのみで25秒）で、通常は duration_seconds に15秒を加えた長さと90秒のうち短い方までです。ナレーションがそれより長い場合は、最後まで再生されます。動画が5秒を超えて長くなる場合は warnings[] に記載されます。請求額が見積額を超えることはありません。
• 字幕では句読点を省き、アクセント記号などのダイアクリティカルマークは保持し、数字は入力どおりに表示します。字幕が有効な場合、音声を生成する前にスクリプトを字幕フォントで検証します。フォントで描画できない文字があると、料金は発生せずに実行が失敗します。
• ナレーションの言語は自動検出されます。
• format explainer を指定した make_faceless は、イラストによる解説動画を作成し、どのアカウントからでも注文できます。tier standard（デフォルト）は60秒までの動画が700クレジットで、それを超える1秒ごとに12クレジットが加算されます。tier pro は1200クレジットに加え、超過1秒ごとに20クレジットで、より丁寧な演出と豊かなシーンが提供されます。見積もりの explainer_tiers には両方の合計額が記載されます。動画の作成には約30分かかります。サービスが混雑している場合、クレジットを確保する前に explainer_busy と Retry-After を返してリクエストを拒否します。指定された時間だけ待ってから再試行してください。
• voice はナレーションの音声を指定します。GET /v1/voices?skill=make_faceless から名前を選んでください。指定しない場合、ナレーションには narrator_en_wise_lady が使われ、英語の解説動画では最速の音声が使われます。ナレーションの言語に合った音声を選んでください。不明な名前、make_ugc の音声、voice_id は、料金が発生する前に拒否されます。make_faceless で使用できるのは、make_faceless 用として一覧にある音声だけです。
• make_faceless の出力は9:16、720pです。resolution に 1080p を指定した場合を除きます。サーバーで顔出しなし動画の生成が無効になっている場合、どちらの呼び出しも paid_render_disabled を返し、料金は発生しません。
• story_not_planned で始まるエラーが発生した実行は、最初のステップで停止しています。その試行ではナレーションを計画できませんでした。料金は発生していないため、新しい Idempotency-Key を使って同じ入力を再実行できます。

make_ugc と create_actor では、出力形式はリクエストとソースに従います。対応形式は9:16、1:1、16:9、解像度は720p、1080pです。指定がない場合は720p、9:16になります。make_faceless も同じ resolution フィールドを受け取り、デフォルトも同じです。

08

ワークフロー

GET /v1/public/workflows では、実行可能なメソッドを一覧表示します。ネイティブメソッドは ugc-product-intro、ugc-faq-answer、faceless-explainer、product-image-story です。website-proof-demo と kinetic-launch はまだ実行できず、理由とともに execution_blocked のままです。

CLIで最短の手順を進めるには、メソッド固有のサンプルから始めます。クレジットを消費するのは plan-run だけで、それ以前のコマンドはすべて無料です。プランを作成する前に brief を編集し、メソッドのピンを保持してください。

clipwright workflow-show faceless-explainer > method.json
jq '{document: {v: 1, method: {method_id: .descriptor.id, version: .descriptor.version, content_digest: .descriptor.content_digest, capability_digest: .capabilities.content_digest}, brief: .descriptor.example.brief, beats: .descriptor.example.beats, claims: [], assets: []}}' method.json > create.json
clipwright plan-create --file create.json > plan.json
jq '{revision, content_digest}' plan.json > approval.json
clipwright plan-approve wfp_example --file approval.json
clipwright plan-quote wfp_example > quote.json
jq '{revision, content_digest, semantic_input_digest, quote_id, idempotency_key: "workflow-example:1"}' quote.json > launch.json
clipwright plan-run wfp_example --file launch.json
clipwright runs run_example

wfp_example を plan.json の plan_id に、run_example を plan-run が出力する実行IDに置き換えてください。見積もりの有効期限は発行から5分後なので、plan-quote の後は速やかに plan-run を実行してください。product-image-story では、各写真を clipwright upload --json でアップロードします。応答には upload_id と content_digest が含まれます。それらをそのままアセットにコピーしてください。写真ごとにアセットを1つ追加します。uploads コマンドは、以前にアップロードしたファイルと同じ識別情報を返します。

clipwright upload mug-front.jpg --json > upload.json
jq '{instance_id: "mug-front", asset_id: .upload_id, content_digest, anchor: {quote: "overall shape"}, provenance: "owner_supplied", rights: "owner_authorized", purpose: "product_proof"}' upload.json > asset.json

{
  "instance_id": "mug-front",
  "asset_id": "upl_00000000000000000000000000000000",
  "content_digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "anchor": {
    "quote": "overall shape"
  },
  "provenance": "owner_supplied",
  "rights": "owner_authorized",
  "purpose": "product_proof"
}

• アカウント所有のプランを作成し、改訂版を保存して、正確な改訂版と content_digest を承認します。計画と承認は無料で、レンダリングも開始しません。改訂版を編集した場合は、新たに承認が必要です。
• 承認済みプランについて、/v1/workflow-plans/{id}/quote に空の本文を POST します。実行リクエストには、その quote_id、revision、content_digest、semantic_input_digest を使用してください。新たに購入を開始する前に expires_at を確認してください。これは見積もりのメタデータです。Idempotency-Key は本文の idempotency_key と一致している必要があります。
• UGCワークフローの見積もりでは、native_quote.quote.warnings に、duration_estimate_sec と credits_estimate が固定価格ではなく推定値であることが明記されます。納品された短尺UGCの料金は、実測した動画に対する price_lines に基づき、各項目は秒単位で切り上げられます。そのため、動画が推定より長い場合、料金は推定額を上回ります。完了した実行の credits_charged を確認してください。long_form_pricing を含むネイティブ見積もりでは、動画全体の秒数ではなく、検証済みの納品済み顔出し区間と、受付時に固定された料金表が適用されます。ネイティブの失敗時条件も引き続き適用されます。
• ネイティブの料金表と失敗時のルールは引き続き適用されます。Faceless の duration_seconds は、見積もりが請求額の上限となる長さを選択します。実測したナレーションの長さによって、実際の納品時間が決まります。音声、字幕、承認された正確なスクリプトには、ネイティブ設定が適用されます。
• 提供する画像ごとに、異なる instance_id、安定した所有済みのアップロード asset_id、content_digest、rights、provenance、purpose、および重複しない単語範囲または曖昧さのない引用を指定して紐付けます。1つのアップロードを複数のインスタンスで再利用できます。一時的な署名付きURLは、見積もり時と起動時に解決されます。
• 元の商品を示す証拠画像は、対応する IMAGE ショットに配置します。生成されるオープニングは説明用です。必要な場合、静止画のみの正確なスライドショー、顧客のみを使ったオープニング、任意のシーン構成は利用できません。
• protected_area は、元画像に対する比率で指定する矩形です。事前検証では、クロップ、PAN モーション、字幕を適用した後もその領域が保持される必要があります。画像の向きや配置を証明できない場合は拒否されます。生成画像が、必要な元画像の証拠に置き換わることはありません。
• アニメーションまたはEXIFチャンクを含む保護対象PNG、およびAPP1（EXIF/XMP）セグメントを含むJPEGは拒否されます。メタデータを除去した、正しい向きの静止画像をエクスポートしてください。カバレッジの判定には、ネイティブの実測25 fpsフレームクロックを使用します。
• アップロードの保持期間と24時間の署名付きURLは、それぞれ独立した制限です。見積もりによってどちらも延長されません。レンダリングと復旧のため、ソースと署名を利用可能な状態に保ってください。受理済みの再送では、元のソースと署名が保持されます。
• 起動に成功すると、レシートと既存のネイティブ Run が返されます。受理済みの同じリクエストを再試行すると、見積もりの期限切れ後やソースの署名が利用できなくなった後でも、その購入を取得できます。GET /v1/runs/{id} で進捗と納品動画を確認してください。
• 非公開プランはトークンのアカウントに属します。
• product-image-story では、生成シーンとオープニング画像に、受理されたアセット順で最初に見つかる、条件を満たした異なる2つの商品証拠画像が使われます。1枚目は商品の形状を示し、2枚目は別の視点を提供します。プランの準備状況とネイティブ見積もりには、選択された枚数と、生成イラストが元画像と異なる場合があることが記載されます。追加の元画像は、紐付けられた画像配置をそのまま保持します。以前に支払い済みのチェックポイントを復旧する場合、元の商品画像による条件付けを検証できないときは、明示的な警告を付けて既存のシーンを再利用します。改訂版と候補（保持された候補や後続の改訂版を含む）にも、この既知の条件付けの制限が引き継がれます。編集後も以前のシーンや配置が維持されるとは限りません。
• 書き込みでは、不明なフィールドと256000 JSONバイトを超えるドキュメントは拒否されます。読み取りでは将来追加されるフィールドや列挙値も受け入れます。読み取りドキュメント内の不明なフィールドは保持されるため、古いクライアントは意図を消去する代わりに、未対応の保存を拒否します。受理済みのナレーション原文は変更しないでください。
• 保存応答を受け取れなかった場合は、同じ base_version/document リクエストを明示して再送してください。それがすでに現在のドキュメントになっている場合、バックエンドは承認をリセットせずにその改訂版を返します。現在のドキュメントが異なる場合は workflow_conflict が返されます。SDK、MCP、CLI は、保存の副作用として承認、見積もり、購入を行いません。
• GET /v1/runs/{id} には workflow が含まれる場合があります。内容は、変更不可のレシート、approved_plan、ネイティブの状態と警告、actual_output、asset_placements、参考情報である beat_dispositions、validation_issues、creative_acceptance=not_reviewed です。approved_plan には brief.reference_profile が含まれないため、ポーリングで同じ内容が繰り返されることはありません。プランに参照元から再現されていない内容は warnings に記載され、GET /v1/workflow-plans/{id} は現在の改訂版全体を返します。下書きを変更しても、実行には購入時の改訂版が保持されます。改訂版やショット候補が、元のレシートを引き継ぐことはありません。
• 検証済みのfaceless精算では、後から任意のジオメトリ情報が欠落しても、アーティファクトのダイジェスト、形式、実測時間が提供されます。配置情報には、アカウント、実行、リクエストに紐付いたチェックポイントが完全な状態で必要です。証拠が欠落している場合は、validation issue とともに null になります。検証済みの空の配置リストは [] です。検証済みのUGC納品では、最終ファイルの実測形式、時間、ダイジェストが提供されます。形式はリクエストではなく、実測した寸法から決まります。バイト数や形式の証拠がないUGC（古い実行を含む）では、actual_output=null となり、output_evidence_unavailable が返されます。ネイティブの video_url は引き続き結果を示します。過去の証拠によって、期限切れのダウンロードURLが更新されたり、人によるクリエイティブの承認が証明されたりすることはありません。
• SDKメソッドは listWorkflows、getWorkflow、createWorkflowPlan、planReferenceRemake、getWorkflowPlan、saveWorkflowPlan、approveWorkflowPlan、quoteWorkflowPlan、runWorkflowPlan です。getRun は workflow の証拠を保持します。CLIコマンドは workflows、workflow-show、plan-create --file、plan-show、plan-save --file、plan-approve --file、plan-quote、plan-run --file です。これらのワークフローコマンドはJSONを出力します。解析前のファイルサイズは1 MiB以下に制限されます。plan-show のファイルを編集し、同じプランの plan-save に渡すことができます。

POST /v1/workflow-plans/{id}/run のリクエスト本文の例です。quote フィールドを承認済みプランの見積もりに置き換え、Idempotency-Key: workflow-example:1 を送信してください。

{
  "quote_id": "wq_example",
  "revision": 1,
  "content_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "semantic_input_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "idempotency_key": "workflow-example:1"
}

09

実行の開始

有料の呼び出しでは、キー以外に Idempotency-Key ヘッダーが1つ必要です。POST /v1/skills/make_faceless/run、POST /v1/runs/{id}/revisions、POST /v1/runs/{id}/candidates、POST /v1/skills/make_ugc/run、POST /v1/skills/create_actor/run、POST /v1/workflow-plans/{id}/run、POST /v1/skills/generate_image/run、POST /v1/skills/generate_video/run、POST /v1/reference-analyses、POST /v1/creator-profiles、POST /v1/trend-searches ではこのヘッダーが必要です。ヘッダーがない呼び出しは、料金が発生する前に 400 idempotency_key_required で拒否されます。

• キーは自分で選びます。再試行と2回目の注文を区別する唯一の手段です。任意の一意な文字列を使えます。呼び出しを再送する可能性がある間は、そのキーを保持してください。
• 同じキーと同じ本文を使うと、すでに開始した実行が返され、2回目の料金は発生しません。通常の再試行が安全なのはこのためです。
• 同じキーで本文が異なる場合は、409 idempotency_key_reused で拒否されます。すでに使用したキーのリクエストを編集するのではなく、新しいリクエストには新しいキーを使ってください。
• 同じ入力で意図的に新しい実行を開始する場合（失敗後の再試行など）は、新しいキーを送信してください。すでに料金を支払った実行はそのまま残ります。
• @clipwright/sdk と @clipwright/mcp-server は、クライアントと入力からキーを自動生成し、attempt=2、3 … を新しいキーに変換します。通常のHTTPでは、キーは自分で選びます。

10

呼び出しが失敗した場合

拒否応答にはすべて、code と message を含む error オブジェクトが付属します。対処方法はメッセージの文面ではなく、拒否の種類によって決まります。

拒否	HTTP	同じ呼び出しを再試行するか	対応方法	課金
rate_limited	429	待機後に再試行する	エラーではなく、バックプレッシャーです。レスポンス本文と Retry-After に、待機する秒数が示されます。	なし。呼び出しは受け付けられていません。
server_error	500, 502, 503	待機後に再試行する	サーバー側の障害です。新しい冪等性キーで2回目の実行を開始しないでください。同じ呼び出しを再試行します。	このレスポンスによる課金はありません。サーバーが開始できなかった実行では、保留されたクレジットが戻ります。開始された実行は、その結果に応じて1回だけ課金されます。
insufficient_credits	402	いいえ。同じ結果になります	停止して、残高と料金をユーザーに伝えてください。どちらも本文に記載されています。再試行しても変わりません。	なし。実行の作成やクレジットの保留より前に、呼び出しが拒否されました。
max_credits_exceeded	402	いいえ。同じ結果になります	停止してください。この呼び出しでは max_credits を超える額が予約されます。両方の数値は本文に記載されています。ユーザーに上限額の引き上げを承認してもらい、hold_credits 以上の max_credits を指定して呼び出しを再試行してください。	なし。実行の作成やクレジットの保留より前に、呼び出しが拒否されました。
debt_outstanding	402	いいえ。同じ結果になります	停止してください。クレジットを購入すると、残高に反映される前に債務が清算され、ブロックが解除されます。	なし。実行の作成やクレジットの保留より前に、呼び出しが拒否されました。
not_admitted	403	いいえ。同じ結果になります	停止してください。このアカウントにはベータ版へのアクセス権がありません。再試行しても購入しても変わりません。サポートにお問い合わせください。	なし。実行の作成やクレジットの保留より前に、呼び出しが拒否されました。
edit_conflict	409	いいえ。同じ結果になります	停止してください。編集の下書きのバージョンが、保存時に基準としたバージョンと異なります。本文にそのバージョンが記載されています。下書きを読み込んでください。すでにドキュメントの内容が反映されている場合は、先行する保存が成功しています。そうでなければ、読み込んだ内容に変更を適用し、そのバージョンを指定して保存してください。	なし。実行の作成やクレジットの保留より前に、呼び出しが拒否されました。
run_not_editable	409	いいえ。同じ結果になります	停止してください。この実行には、読み込みや保存ができる編集の下書きがありません。本文には状態と理由が記載されています。実行状態の shots にも同じ内容が記載されています。	なし。実行の作成やクレジットの保留より前に、呼び出しが拒否されました。
editing_closed	503	いいえ。同じ結果になります	停止してください。有料編集は現在利用できません。理由は本文に記載されています。課金は発生せず、実行も作成されていません。実行の shots にある paid_edits に、利用開始時期が示されます。	なし。実行の作成やクレジットの保留より前に、呼び出しが拒否されました。
edit_ceiling_reached	409	いいえ。同じ結果になります	停止してください。元の実行では、許可されている上限まで改訂またはショット候補（それぞれ別々にカウント）が実行中、あるいは失敗して未完了です。本文に上限、件数、実行が記載されています。実行中のものは GET /v1/runs/{id} で確認し、完了後に次を開始してください。こちら側の原因で失敗した場合は、サポートが改訂の失敗上限を引き上げます。	なし。実行の作成やクレジットの保留より前に、呼び出しが拒否されました。
edit_invalid	422	いいえ。同じ結果になります	停止してください。ドキュメント、またはショット候補が要求する操作が、編集対象の実行のルールに違反しています。issues に各問題が順番に記載されています。リクエストを修正してください。ルールは実行の shots に記載されています。	なし。実行の作成やクレジットの保留より前に、呼び出しが拒否されました。
workflow_invalid	400	いいえ。同じ結果になります	停止してください。すべての問題と警告を確認し、ワークフロードキュメントを修正してください。承認、見積もり、有料での開始は、それぞれ明示的に別の呼び出しで行います。	なし。実行の作成やクレジットの保留より前に、呼び出しが拒否されました。
workflow_conflict	409	いいえ。同じ結果になります	停止してください。保存済みのプランを読み込み、リビジョンとドキュメントを元のリクエストと比較してください。開始されたか不明な場合は、元のリクエストと冪等性キーを使って確認してください。新しいキーを使うと二重に課金される可能性があります。	この呼び出しによる課金はありません。先に開始された実行は、その結果に応じて1回だけ課金されます。元のリクエストとキーを使えば、その実行が返されます。
workflow_not_ready	409	いいえ。同じ結果になります	停止してください。すべての問題と警告を確認してください。準備状態を解決した後、キーを指定した有料開始の前に、選択したリビジョンを明示的に承認して見積もりを取得してください。	なし。実行の作成やクレジットの保留より前に、呼び出しが拒否されました。
client_error	400, 401, 403, 404, 409, 410, 413, 415, 422, 503	いいえ。同じ結果になります	停止してください。リクエスト自体が拒否されました。メッセージを確認して呼び出しを修正し、再送信してください。	この呼び出しによる課金はありません。実行は作成されず、クレジットも保留されていません。同じ Idempotency-Key を使った先行の実行（409 idempotency_key_reused）は、その結果に応じて1回だけ課金されます。

以下は、API が error.code に設定するすべてのコードです。見慣れないコードでも、行はステータスによって選ばれるため、上記の対応する行に従ってください。

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• analysis_enqueue_failed
• aspect_conflict
• asset_cap_exceeded
• asset_ingest_cap_exceeded
• asset_not_found
• asset_not_ready
• assets_disabled
• creator_profile_limited
• creator_profile_not_found
• creator_url_unsupported
• debt_outstanding
• deletion_held
• edit_ceiling_reached
• edit_conflict
• edit_invalid
• editing_disabled
• editing_not_priced
• editing_window_not_set
• explainer_busy
• feedback_limited
• film_draft_limited
• film_draft_not_found
• film_draft_stale
• film_run_not_found
• film_voice_not_ready
• generations_disabled
• generations_marking_pending
• idempotency_key_required
• idempotency_key_reused
• ingest_enqueue_failed
• insufficient_credits
• insufficient_scope
• internal_error
• invalid_image
• invalid_request
• malformed_body
• max_credits_exceeded
• no_changes
• not_found
• own_agent_disabled
• own_agent_marking_pending
• paid_render_disabled
• payload_too_large
• proposal_expired
• proposal_not_found
• proposal_not_ready
• proposal_stale
• rate_limited
• reference_analysis_disabled
• reference_analysis_limited
• reference_analysis_not_found
• reference_not_analyzable
• reference_not_usable
• reference_url_unsupported
• rejected_field
• revision_needs_generated_unit
• rights_not_confirmed
• run_media_in_use
• run_not_editable
• run_not_finished
• run_not_found
• script_encoding_lost
• source_aspect_mismatch
• source_not_usable
• trend_page_unavailable
• trend_search_limited
• trend_search_not_found
• trends_unavailable
• unauthorized
• unknown_field
• unsupported_combination
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upload_digest_mismatch
• upload_expired
• upload_in_use
• upload_not_finished
• upload_size_mismatch
• upstream_error
• url_fetch_busy
• url_fetch_failed
• url_fetch_rate_limited
• url_fetch_refused
• url_import_disabled
• workflow_conflict
• workflow_invalid
• workflow_not_ready

11

制限

• 60秒あたり、有料リクエストは60件、無料リクエストは300件です。ウィンドウはキーごとではなくアカウントごとにカウントされるため、キーを増やしても処理量は増えません。
• アカウントごとに、プレゼンター付き動画は3本、顔出しなし動画は2本を同時に作成できます。残りは拒否されず、キューに入ります。多くのアカウントが同時にレンダリングしている場合、実行が順番待ちになることもあります。
• 解説動画（format が explainer の make_faceless）は例外です。クレジットを予約する前に explainer_busy と Retry-After を返して拒否されます。このアカウントで動画の処理中（同時に1本まで）の場合は 429、すべての動画スロットが使用中の場合は 503 です。後でもう一度お試しください。
• レート制限による拒否では、Retry-After と本文に待機する秒数が示されます。大きい方の値に従ってください。
• クリップあたりのインサートは99個までで、その間に登場するアクターは最大16回です。どちらも送信した単語インデックスからカウントされるため、それを超える入力は課金前に拒否されます。
• cover_words は、インサートがカバーする発話単語数を示し、アンカーの最初の単語から数えます。インサートは、最初にカバーされない単語の位置で終わります。そのため、カバー範囲が接する2つのインサートは隣接し、その間にアクターのショットは入りません。
• カバーされない単語の割合によって、クリップ内で顔が映る割合が決まり、音声の速度によって変わることはありません。単語の長さは変動します。560語のスクリプトで19%を指定すると、約16～22%になります。短いスクリプトではばらつきが大きくなり、音声が異なれば結果も変わります。
• 単語を1つ変えるだけで、見た目だけでなく料金も変わる選択肢が2つあります。単語0をアンカーにしたインサートは最初の単語の前の無音部分を含みます。単語1をアンカーにするとアクターの登場が1回増え、登場回数ごとに料金が加算されます。最後の単語までカバーするとクリップの最後まで続き、同様に最後の登場がなくなります。
• 見積もりでは、割合が estimatedFaceWordShare として返されます。このフィールドを確認してください。estimatedFaceSeconds を estimatedTotalDurationSec で割らないでください。この2つは異なる問いに答える値です。前者は発話速度の範囲のうち遅い側を基準に保持するクレジット量、後者はクリップの予想再生時間を示します。その比率は、何かの割合を表すものではありません。

12

この API が決して行わないこと

• 何かを公開すること。ファイルと署名付きリンクを返しますが、公開先はご自身で決めてください。
• 開始済みの実行をキャンセルすること。そのためのエンドポイントはありません。
• 次の make_ugc フィールドを受け付けること：character、broll_url、disclosure_overlay、webhook_url。課金前にフィールド名を示して拒否され、受け付けて黙って無視されることはありません。
• 指定されたフォーマットや解像度を、通知なしに変更すること。不一致がある場合は、警告付きで調整されるか、有料呼び出しの前に拒否されます。
• 折り返し連絡すること。Webhook はありません。GET /v1/runs/{id} で実行を確認してください。
• キーを再表示したり、バックアップから復元したりすること。

13

そのほかの注意点

• 警告を返し、黙って処理することはありません。対応できなかった内容は、同じ実行の warnings[] に名前付きで返されます。パラメーターが説明なしに消えることはありません。
• MCP サーバー。@clipwright/mcp-server は同じ仕様をツールとして公開し、その tools/list がこのページの機械可読形式です。