動画生成
動画生成に対応した Model ID でタスクを作成し、ステータスをポーリングしてから動画ファイルをダウンロードします。
動画生成は非同期で行われます。リクエストはタスクを作成するだけで、動画を取得できるのはタスクが成功した後です。始める前に、モデルページで対応する解像度、長さ、解像度ごとの料金を確認してください。
リクエストエンドポイント
動画生成では、タスクの作成に 1 つ、その後の処理に 3 つのエンドポイントを使用します。
| メソッドとパス | 用途 |
|---|---|
POST /v1/videos | 動画生成タスクを作成する |
GET /v1/videos/{id} | タスクのステータスを確認する |
GET /v1/videos/{id}/content | 完成した動画をダウンロードする |
DELETE /v1/videos/{id} | タスクを削除する(モデルのインターフェースが対応する場合) |
すべてのパスで https://api.vergora.ai を使用し、他のリクエストと同じ Authorization: Bearer YOUR_VERGORA_API_KEY ヘッダーを付けます。課金されるのはタスクの作成のみです。
リクエスト例
POST https://api.vergora.ai/v1/videos{
"model": "YOUR_VIDEO_MODEL_ID",
"prompt": "雨の降る通りを流れていく紙の船、カメラがゆっくりと寄っていく",
"resolution": "720p",
"ratio": "16:9",
"duration": 5
}作成時のレスポンスには、タスクの id と初期ステータスが含まれます。以降のすべてのリクエストで必要になるため、id を保存しておいてください。
OpenAI 互換の動画インターフェースを使用するモデルでは、duration、resolution、ratio の代わりに seconds と size(例:"8" と "1280x720")を指定します。各モデルページの「API」タブに、正しい形式のリクエスト例が表示されます。
リクエストフィールド
| フィールド | 説明 |
|---|---|
model | 動画生成に対応した Model ID |
prompt | 被写体、動作、シーン、カメラワーク |
content | prompt の代わりに使う構造化入力(対応している場合) |
input_reference | 先頭フレームに使う参照画像の URL |
duration | 動画の長さ(秒) |
resolution | 出力解像度(720p、1080p など) |
ratio | アスペクト比(16:9 など。aspect_ratio も可) |
| その他のパラメーター | モデルが対応している場合にのみ使用 |
content には、テキスト、参照画像、入力動画を含めることができます。その他のパラメーターには seed、watermark、generate_audio、camera_fixed、service_tier があり、対応しているモデルにのみ送信してください。Seedance 2.0 / 2.5 は seed と camera_fixed のどちらも受け付けないため、これらのモデルではゲートウェイが除外します。Wan 2.5 / 2.6 と W3.0 では、generate_audio の代わりに audio(ブール値、デフォルトで有効)を使用します。
リクエストボディは JSON で送信します。入力動画を使用する場合は、公開リンクまたはアップロード済みファイルのキーを渡します(例:タイプが video_url の content 項目。後述の「参照画像と参照動画」を参照)。動画には data: URI を使用できません。入力動画を含むリクエストは、モデルの「入力動画あり」の料金で課金されます。
参照画像と参照動画
参照画像や参照動画は、次のいずれかの形式で指定できます。同じフィールドでどの形式も受け付け、ゲートウェイが自動的に判別します。
| 形式 | 例 | 備考 |
|---|---|---|
| 公開リンク | https://cdn.example.com/clip.mp4 | モデルプロバイダーがダウンロードするため、公開インターネットからアクセスできる必要があります |
| アップロード済みファイル | uploads/u42/20261112/0123…cdef.mp4 | POST /v1/uploads が返すキー(後述)。リクエストがプロバイダーに届く前に、一時リンクに置き換えられます |
| インラインデータ | data:image/png;base64,… | 画像のみ。動画はインラインでは受け付けません |
参照は、モデルのインターフェースが想定する場所に指定します。先頭フレームの画像は input_reference に、または content のタイプが image_url、video_url の項目に入れます。
{
"model": "YOUR_VIDEO_MODEL_ID",
"content": [
{ "type": "text", "text": "同じシーンの夜、カメラがゆっくりと寄っていく" },
{
"type": "image_url",
"image_url": { "url": "https://cdn.example.com/frame.png" },
"role": "reference_image"
},
{
"type": "video_url",
"video_url": { "url": "uploads/u42/20261112/0123…cdef.mp4" },
"role": "reference_video"
}
],
"resolution": "720p",
"duration": 5
}モデルが受け付ける参照の数や、参照動画に対応しているかどうかは、モデルページに記載されています。参照動画は、それぞれの長さが課金額に加算されます。
参照ファイルをアップロードする
ファイルが公開リンクではなく手元のマシンにある場合は、先にアップロードし、返されたキーを使用します。
- アップロード先のアドレスをリクエストします。ファイルのタイプと、バイト単位の正確なサイズを送信します。
POST https://api.vergora.ai/v1/uploads{ "content_type": "video/mp4", "size": 2376873 }- レスポンスには、
key、upload_url、method(PUT)、送信するheadersが含まれます。これらのヘッダーをそのまま付けて、ファイルをupload_urlにアップロードします。このアドレスの有効期限は 15 分で、宣言したタイプとサイズのファイルのみを受け付けます。
{
"object": "upload",
"key": "uploads/u42/20261112/0123456789abcdef0123456789abcdef.mp4",
"upload_url": "https://…",
"method": "PUT",
"headers": { "Content-Type": "video/mp4" },
"expires_at": 1794500000
}- リクエストで参照画像や参照動画を指定する箇所に、この
keyを使用します。
| タイプ | 対応形式 | サイズ上限 |
|---|---|---|
| 画像 | JPEG、PNG、WebP、GIF | 20 MB |
| 動画 | MP4、MOV、WebM | 200 MB |
キーは、作成したアカウントでのみ使用できます。アップロードするファイルは、宣言した種類の画像または動画である必要があり、そうでない場合、そのファイルを使用するリクエストは拒否されます。アップロードされたファイルは一定期間のみ保持されます。キーが使用できなくなった場合は、再度アップロードしてください。
タスクのステータスを確認する
動画タスクの完了には、通常数十秒から数分かかります。数秒ごとにステータスをポーリングしてください。
GET https://api.vergora.ai/v1/videos/{id}| ステータス | 意味 |
|---|---|
queued | 開始待ち |
running または in_progress | 生成中 |
succeeded または completed | 完了。動画をダウンロードできます |
failed または cancelled | 動画が生成されずに終了。事前に確保された金額は返金されます |
レスポンスは、モデルのインターフェースの構造をそのまま保持します。トークン単位で課金されるモデルでは、課金に使用されたトークン数を含む usage オブジェクトも返されます。
タスクが作成されても、動画が生成されたとは限りません。トラブルシューティングやコストの確認のために、タスクの id を保存しておいてください。
動画をダウンロードする
GET https://api.vergora.ai/v1/videos/{id}/contentレスポンスボディは動画ファイルです(通常は MP4)。タスクが成功するまで、このエンドポイントはコード video_not_ready とともに 409 を返します。ダウンロードをループで再試行するのではなく、ステータスのポーリングを続けてください。生成されたファイルは一定期間しか保持されないため、タスクが成功したら早めにご自身のストレージに保存してください。
料金と再試行
動画モデルの料金は解像度ごとに設定されており、動画 1 秒あたり、または 100 万トークンあたりで課金されます。すべての料金はモデルページに記載されています。
- タスクを作成すると、リクエストで指定した解像度、アスペクト比、長さ、および入力動画に基づく見積額が、残高から事前に確保されます。リクエストでこれらが指定されていない場合は、1080p、16:9、15 秒として見積もられます。
- タスクが成功すると、実際の使用量(モデルが報告したトークン数、または生成された動画の秒数(1 秒単位))に基づいて料金が確定します。確定額が確保額を超えることはありません。使用量が少なければ差額が返金され、多くても超過分は請求されません。
- タスクが失敗した場合やキャンセルされた場合は、確保額が全額返金されます。ステータスの確認と動画のダウンロードは無料です。
| レスポンス | 意味 |
|---|---|
403 insufficient_user_quota | 残高が見積額に足りません。タスクは作成されません |
503 model_price_not_configured | このモデルの動画料金がまだ設定されていません |
409 video_not_ready | タスクが成功する前にダウンロードがリクエストされました |
POST /v1/videos を送信するたびに新しいタスクが作成され、それぞれ個別に課金されます。タイムアウトした場合は、リクエストを再送信する前に、タスクがすでに作成されていないかをリクエストログで確認してください。