Clipwright

Clipwright API

スクリプトをリップシンク付きUGC動画に変換する単一のHTTP APIです。エージェントによって駆動されるように設計されています。すべての呼び出しは単一のJSONリクエストであり、すべての拒否は次に何をすべきかを示し、どこにも公開されません。このページのすべての単語は、https://clipwright.io/docs.md, にある単一のマークダウンファイルでもあり、https://clipwright.io/llms.txt. にあるエージェント向けの短い契約でもあります。

認証

すべての呼び出しは 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：完成した動画の毎秒につき30クレジット。秒単位で切り上げられます。
• セグメントまたはインサートを使用した make_ugc：顔が画面に表示される毎秒につき10クレジット、配信された動画には最低400クレジット。顔のない秒数は無料で、ファイルが配信されない実行は、ベンダーにすでに支払いが行われた場合でも、まったく費用がかかりません。顔の時間は動画全体で合計され、セグメントごとではなく一度だけ切り上げられます。これらのフィールドは、デプロイメントでの長文形式の認定が必要です。オフになっている場合、課金前に名前で拒否されます。
• 品質が medium の create_actor：ポートレートに10クレジット、追加フォーマットごとに10クレジット。
• 品質が high の create_actor：ポートレートに20クレジット、追加フォーマットごとに20クレジット。
• クレジットはパックで購入されます：1000クレジットで10.00ドル、1回の支払い、サブスクリプションはありません。

使う前に尋ねてください：どちらのスキルの見積もりエンドポイントも無料です。その回答の価値はスキルによって異なります。

• make_ugc：見積もりはスクリプトの言葉から読み取られる推定値です。請求額は完成した動画で測定されたもの（プレーンスクリプトメーターではその時間、顔メーターではその顔の秒数）に従うため、請求額は見積もりを上回ることも下回ることもあります。
• create_actor：見積もりは、要求したすべてのフォーマットの価格を示します。これは支払う最大額です。ポートレートと実際に公開されたバリアントに対して課金されます。生成されなかったフォーマットは warnings[] に名前が示され、費用はかかりません。

失敗した実行の費用もスキルによって異なります：

• プレーンスクリプトからの make_ugc：配信作業がベンダーに到達した後に失敗した実行は課金されます。それ以前に失敗したものは無料で、当社が停止、紛失、または自ら拒否したものも、ベンダーにすでに支払いが行われた場合でも無料です。顔メーターでは、失敗に対しては一切課金されません。
• create_actor：失敗した実行は、ベンダーにすでに支払いが行われた場合でも、まったく費用がかかりません。アクターが届かなかったためです。

04

エンドポイント

エンドポイント	クレジット消費	機能
GET /health	なし	API自体の生存確認。キーなしで応答します。
GET /v1/voices	なし	voice または voice_id で指定できる音声。
GET /v1/account	なし	キーの背後にあるアカウントの残高、負債、保留。
POST /v1/skills/make_ugc/quote	なし	この入力で make_ugc 呼び出しの価格を提示します。課金はありません。
GET /v1/runs/{id}	なし	任意のスキルの1回の実行の状態、その警告、および動画URL。
POST /v1/skills/make_ugc/run	あり	動画の実行を開始し、すぐに run_id で応答します。結果を取得するには実行をポーリングします。
GET /v1/public/skills	なし	キーなしでスキルとその入力のカタログ。
GET /v1/actors	なし	アカウントに保存されたアクター。make_ugc が受け取る id 付き。
DELETE /v1/actors/{id}	なし	保存されたアクターを忘れます。実行中のアクターは保持されます。
GET /v1/actors/{id}/defaults	なし	インサート内の人物に対する保存されたアクターのデフォルトポリシーを読み取ります。
POST /v1/actors/{id}/defaults	なし	インサート内の人物に対する保存されたアクターのデフォルトポリシーを設定します。実行で上書きできます。
POST /v1/skills/create_actor/quote	なし	この入力で create_actor 呼び出しの価格を提示します。課金はありません。
POST /v1/skills/create_actor/run	あり	アクターの実行を開始し、すぐに run_id で応答します。結果を取得するには実行をポーリングします。
POST /v1/uploads	なし	画像バイトを受け取り、make_ugc と create_actor が受け入れる https URL を返します。

どちらのスキルの実行も同じ場所、GET /v1/runs/{id} から読み戻され、次の状態を遷移します：queued、generating、scripting、tts、avatar、compositing、uploading、succeeded、failed。

05

スキルとその入力

make_ugc。リップシンク付きUGC動画の生成を開始します。選択した音声モデルのテキスト制限内でスクリプトを指定します。アクターは actor_id（list_actors からの保存済みアクター）または image から取得され、それ以外の場合はデフォルトのアクターが使用されます。フォーマットと解像度はリクエストとソースに従い、デフォルトは 1080x1920 です。キャプションはオプトインです：最初にユーザーに確認してください。レンダラーがまだ対応していないフィールドには、独自の説明に「未対応」の注記があります。推測せずにそれを読んでください。

生成前に quote_ugc を呼び出し、コストを表示してください。これは動画を待ちません：実行を開始し、すぐに run_id を返します。その後、その run_id で get_run をポーリングして、状態が 'succeeded'（video_url）または 'failed' になるまで待つ必要があります。支払い済みのベンダージョブをまだ保持している 'failed' 実行は、'queued' に戻り、後で 'succeeded' に到達できます。その場合は常に warnings[] に名前が示されます。attempt=2,3,… を渡すと、同じ入力に対して意図的に新しい実行を開始します（失敗後の再試行）。

フィールド	必須	意味
script	任意	アクターが話す言葉。segments が話すテキストを提供しない限り必須。セグメントとテキストアンカー付きインサートは、サーバーでの長文形式の認定が必要です。音声モデルによるスクリプト制限：eleven_v3：5000文字。eleven_flash_v2_5：10000文字。eleven_turbo_v2_5：10000文字。カウントにはスペース、オーディオタグ、強勢記号が含まれます。絵文字は2文字としてカウントされる場合があります。単語数の制限はありません。時間と価格は測定されるまでの推定値です。ロシア語の強勢：強勢母音を小文字の単語内で大文字で書きます（「потОм」、「зАмок」）。eleven_v3 はそれを強勢記号 U+0301（「пото́м」）として受け取ります。直接入力された記号は保持されます。単語の先頭の大文字は大文字のままになり、2番目の大文字または単語内の大文字の子音（すべて大文字、「ВУЗы」）を含む単語はそのまま残ります。単語内の単一の大文字母音は常に強勢として読み取られるため、「Яндекс Еда」と書き、「ЯндексЕда」とは書かないでください。ロシア語で書くユーザーに、この方法で強勢をマークできることを伝えてください。eleven_flash_v2_5 と eleven_turbo_v2_5 はコストが低いですが、強勢記号を誤って読み取ります：大文字は変更されずに届きます。
segments	任意	順序付けられたアクターと画像のセグメント。サーバーでの長文形式の認定、captions=false、1080p が必要です。画像メディアには明示的な broll_policy=anyone が必要です。
inserts	任意	全ナレーションにわたるテキストアンカー付き画像インサート。それぞれがアンカーから cover_words の話された単語をカバーします。サーバーでの長文形式の認定、captions=false、1080p、明示的な broll_policy=anyone が必要です。
person	任意	未対応：person はまだ対応していません。このリクエストはデフォルトのアクターを使用します。list_actors から actor_id を選択するか、image を提供して別の顔を選択してください。
actor_id	任意	list_actors からの保存済み Clipwright アクターID。actor_id、image、person のいずれかを選択してください。組み合わせないでください。voice または voice_id がない場合、音声はアクターの性別に従います。actor_gender と組み合わせないでください。
image	任意	アクターの写真の公開 https URL（PNG、JPEG、WebP、最大10 MB）。ディスク上のファイルは、最初に upload_image（POST /v1/uploads）を通過させ、返された URL を渡してください。使用できないソース（プライベートまたはループバックホスト、http、到達不能、リダイレクト、10 MB 超、またはこれらの画像タイプのいずれでもない）は、課金前に拒否されます（unusable_source）。顔の性別は検出しません：actor_gender または voice を渡すか、デフォルトの男性音声が警告付きで使用されます。
actor_gender	任意	image 内の顔の性別：female | male。image とのみ使用：その性別のデフォルト音声を選択します（female：sarah、male：george）。actor_id（性別が既知）と組み合わせた場合、および image なしでは拒否されます。明示的な voice または voice_id が優先され、応答は actor_gender が何も変更しなかったことを警告します。
name	任意	未対応：name はまだ対応していません。レンダラーには届きません。
broll_policy	任意	保存のみ：Bロール用の保存済みポリシー。anyone はアクターを含む人物を許可し、no_actor はアクターを除外し、no_people は手を含むすべての人物を除外します。セグメント化されたメディア生成は閉じられています。この設定は保存のみで、アクターのみの動画には影響しません。実行の上書きはアカウントのアクターデフォルトよりも優先されます。それ以外の場合は no_people。
captions	任意	未対応：キャプションが要求されましたが、このプロトタイプ（ステージB）ではレンダリングされません。
caption_style	任意	未対応：caption_style は対応していません。キャプションはこのプロトタイプ（ステージB）ではレンダリングされません。
look	任意	未対応：look はまだ対応していません。レンダラーには届きません。
aspect_ratio	任意	出力フォーマット：9:16 | 1:1 | 16:9。省略時は 9:16 で、別の形状のソースは警告付きで 9:16 にスナップされます。image を渡すときは常に明示的に渡してください。リクエストとソースの間に15%を超える不一致がある場合、課金前に拒否されます（aspect_conflict）。
resolution	任意	出力解像度：720p | 1080p | 4k（短辺 720 / 1080 / 2160 px）。省略時は 1080p。
voice	任意	list_voices からの音声名。キュレーションされたプリセット：owner_ru_clone | sarah | george | eric | daria_ru_female（owner_ru_clone はロシア語のクローン音声）。API は list_voices が返さない名前を、課金前に拒否します。省略時はアクターの性別のデフォルト音声：actor_id の性別、image の actor_gender、またはデフォルトのアクターと actor_gender なしの image の場合は george。voice_id とは相互に排他的です。
voice_id	任意	カタログ外の音声の生のベンダー音声ID（16〜32文字の英数字）。遅延チェック：不明なIDはリクエストではなく実行を失敗させます。voice とは相互に排他的です。
tts_model	任意	音声モデル：eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5。省略時は選択したプリセットのモデル（list_voices に表示されます。すべてのプリセットは eleven_v3 を話します）または生の voice_id の場合は eleven_v3。eleven_v3 は最も表現力が高く、強勢記号を読み取る唯一のモデルです（ロシア語の単語内の大文字母音「потОм」は1つになります。script を参照）。eleven_flash_v2_5 と eleven_turbo_v2_5 はロシア語以外の言語向けの安価な代替手段です。音声モデルによるスクリプト制限：eleven_v3：5000文字。eleven_flash_v2_5：10000文字。eleven_turbo_v2_5：10000文字。カウントにはスペース、オーディオタグ、強勢記号が含まれます。絵文字は2文字としてカウントされる場合があります。単語数の制限はありません。時間と価格は測定されるまでの推定値です。
disclosure_overlay	任意	受け入れられる値：true | false。
background	任意	受け入れられる値：white | blur | contain。

create_actor。架空の成人を説明する言葉から、このアカウント用のパーソナルアクターを作成します。正確に1つの顔を持つ9:16のポートレートと、そこから編集された他の要求されたフォーマット。すぐに run_id を返します。get_run を 'succeeded'（created_actor.actor_id、その後 make_ugc に actor_id として渡します）または 'failed' になるまでポーリングします。公開された各画像は、見積もりが示す価格で課金されます。拒否された説明と使用できないポートレートは無料です。生成がオフの場合、呼び出しは actor_generation_disabled で失敗します。

フィールド	必須	意味
description	必須	架空の成人を表す言葉：外見、服装、設定。実在の人物や類似した人物の名前を指定すると、課金前に拒否されます（actor_prompt_refused）。
gender	必須	female | male。俳優の性別と、この俳優を使用する動画のデフォルト音声を固定します。
approximate_age	必須	年齢のおおよその値（18〜90歳）。俳優は成人です。
name	必須	list_actors に表示される名前。
aspect_ratios	任意	作成するフォーマット：9:16 | 1:1 | 16:9。常に9:16を含みます。省略時は3つすべて。本人確認チェックに失敗したフォーマットは課金されず、警告に名前が記載されます。
quality	任意	画像品質：medium | high。省略時はmedium。画像あたりの価格はこれに依存し、見積もりは課金前に表示されます。

出力形式はリクエストとソースに従います。対応フォーマットは9:16、1:1、16:9、解像度は720p、1080p、4kです。指定がない場合は9:16の1080pになります。

06

実行の開始

有料の呼び出しには、キー以外に1つのヘッダーが必要です：Idempotency-Key。POST /v1/skills/make_ugc/run と POST /v1/skills/create_actor/run にはこれが必要で、これがない呼び出しは、課金前に400 idempotency_key_requiredで拒否されます。

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

07

呼び出しが失敗した場合

すべての拒否には、コードとメッセージを含むエラーオブジェクトが含まれます。対処方法は、テキストではなく拒否の種類によって決まります：

拒否	HTTP	同じ呼び出しを繰り返すか？	対処方法
rate_limited	429	はい、待機後	バックプレッシャーであり、エラーではありません：レスポンスは待機秒数をRetry-Afterと本文で示します。
server_error	500、502、503	はい、待機後	障害はサーバー側にあります。新しいべき等キーで2回目の実行を開始しないでください：同じ呼び出しがリトライです。
insufficient_credits	402	いいえ、同じ回答が返ります	停止して、残高と価格を相手に伝えてください。両方とも本文にあります。繰り返してもどちらも変わりません。
debt_outstanding	402	いいえ、同じ回答が返ります	停止してください。クレジットを購入すると、残高に反映される前に負債が清算され、ブロックが解除されます。
not_admitted	403	いいえ、同じ回答が返ります	停止してください。アカウントにベータアクセスがありません。リトライも購入もそれを変えません。オペレーターに問い合わせてください。
client_error	400、401、404、409、413、415	いいえ、同じ回答が返ります	停止してください。リクエスト自体が拒否されました：メッセージを読み、呼び出しを修正し、再送信してください。

これらはAPIがerror.codeに入れるすべてのコードです。見たことのないコードでも、上記の行に従います。行はステータスによって選択されるためです：

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• aspect_conflict
• debt_outstanding
• idempotency_key_required
• idempotency_key_reused
• insufficient_credits
• internal_error
• invalid_image
• invalid_request
• malformed_body
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• rejected_field
• script_encoding_lost
• unauthorized
• unknown_field
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upstream_error

08

制限

• 60秒あたり有料リクエスト60件、無料リクエスト300件。ウィンドウはキーごとではなくアカウントごとにカウントされるため、追加のキーでスループットは増えません。
• アカウントごとに同時に3つのレンダリングが実行されます。残りはキューに入り、拒否されません。
• レート制限による拒否は、Retry-Afterと本文で待機秒数を示します。大きい方を尊重してください。
• クリップあたり49のインサート、およびその間の俳優の登場は最大6回。両方とも送信した単語インデックスからカウントされるため、より多くを要求する入力は、支払い前に拒否されます。
• cover_words は、インサートがカバーする話し言葉の単語数を示し、アンカーの最初の単語からカウントされます。インサートは、カバーされていない最初の単語が始まるところで終了するため、カバレッジが接する2つのインサートは隣接し、間に俳優のショットが残りません。
• カバーされずに残した単語の割合が、クリップのうち顔が表示される割合を決定し、音声の速度には依存しません。単語の長さは変動します：560語のスクリプトで19%を要求した場合、997回のシミュレーション実行のうち16〜22を実現し、5万回では15〜24の範囲内に収まりました。これらの数値は、このプロファイルの音声とその長さで測定されました。短いスクリプトではばらつきが大きくなり、異なる音声では数値が変わります。
• 2つの単語の選択が、見た目だけでなく価格を変えます。単語0にアンカーされたインサートは、最初の単語の前の無音を所有します。単語1にアンカーすると、俳優の追加の登場が残り、各登場は別々の有料ジョブです。最後の単語に達するカバレッジは、クリップをその終わりまで引き伸ばし、同じ方法で最後の登場を削除します。
• 見積もりは、estimatedFaceWordShareとして割合を報告します。そのフィールドを読んでください。estimatedFaceSecondsをestimatedTotalDurationSecで割らないでください。これら2つは異なる質問に答えます—前者は発話範囲の低速端で保持するリザーブ、後者はクリップの予想実行時間—そしてそれらの比率は何かの割合ではありません。

09

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

• 何も公開しません。ファイルと署名付きリンクを返します。その行き先はあなたが決めることです。
• 開始した実行をキャンセルしません。そのためのエンドポイントはありません：ベンダーが作業を受け取ったら、当社側で停止しても費用は戻りません。
• これらのフィールドを受け入れません：character、broll_url、webhook_url。これらは課金前に名前で拒否され、受け入れられて静かに無視されることはありません。
• 要求したフォーマットや解像度を変更しても通知しません。不一致は警告付きで調整されるか、有料呼び出し前に拒否されます。
• コールバックしません。ウェブフックはありません：GET /v1/runs/{id}で実行を読み取ってください。
• キーを2回表示したり、バックアップから復元したりしません。

10

その他知っておくべきこと

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