01
長さと解像度は価格つまみであって既定値ではありません
多くの動画エンドポイントは選択した解像度での出力秒あたりで課金します。duration_seconds を 5 から 10 にすればおよそ倍、解像度を一段上げればさらに倍です。どちらもエンドポイントのスキーマで価格に影響すると明示されているので、見積もりは請求書ではなく操作の隣に置いてください。
動画 API ソリューション
プロンプトや一枚の静止画から、納品できる動画へ。
動画はたいていのプロダクトで最も高く、最も待たされる生成です。その二つを決めるのはリクエスト本文の三つのフィールドで、タスクはそれを送った通信が切れたあともずっと動き続けます。
解決する課題
動画だけが他のタスクと違う点
動画は「遅い画像生成」ではありません。長さ、解像度、音声スイッチが支払額と待ち時間を決め、しかも一コマも描かれないうちに決まります。
02
生成音声は別レートです
generate_audio があるエンドポイントでは、この真偽値がリクエストを別のレートへ移します。フォームがこれを隠すと、毎回こっそり高いほうを送ることになります。
03
HTTP レスポンスは動画ではありません
createTask は queued 状態の taskId とともに 202 Accepted を返します。生成はサーバー側で数分続きます。元のソケットで待つ実装はタイムアウトし、そのあいだもタスクと課金は進みます。
実装方針
先に値段を確定し、送信は一度だけ
POST /api/v1/jobs/quote で実際の本文を見積もり、返ってきた金額を表示してから、同じ本文を quoteId、expectedCost、保存済みの Idempotency-Key とともに createTask へ送ります。二回の呼び出しのあいだに価格が動けば、業務コード 40901 で弾かれます。あとから請求書で驚くことはありません。
作成リクエストはモデル、検証済みの入力、任意のコールバックを運びます。HTTP 202 は受理であって完了ではありません。
POST /api/v1/jobs/createTask
POST /api/v1/jobs/createTask
Authorization: Bearer $SPICY_API_KEY
Idempotency-Key: 7b1f0c2e-9a4d-4f31-8c67-2b5e0d9a1c44
Content-Type: application/json
{
"model": "<publisher>/<model>/text-to-video",
"input": {
"prompt": "A slow aerial drift over a misty pine forest at sunrise",
"duration_seconds": 5,
"resolution": "1080p",
"generate_audio": true
},
"callBackUrl": "https://example.com/hooks/spicyapi"
}202 Accepted
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}契約
先に押さえておく項目
| フィールド / ヘッダー | 値・上限 |
|---|---|
| POST /api/v1/jobs/createTask | 202 Accepted · state queued |
| duration_seconds · resolution · generate_audio | price-affecting fields |
| Idempotency-Key | 24 h · scoped to one API key |
| output.assets[].expiresAt | signed URL · results kept 14 days |
横にスワイプして全項目を確認できます。
導入
最初の呼び出しから本番まで
- 01モデルページでエンドポイントを決め、model の値をそのままコピーします。末尾のタスク種別も値の一部です。
- 02送るつもりの本文を見積もり、estimatedCost、quantity、unit を送信ボタンの隣に表示します。
- 03バックエンドから Idempotency-Key 付きで送信し、data.taskId を自分のレコードに保存して、すぐにクライアントへ返します。
- 04署名付きコールバックで締め、必要なら指数バックオフの recordInfo を補助に使い、URL が切れる前にファイルを取得します。
向き不向き
この方法が向いている場面
こんなときに選ぶ
- 広告、予告、ループ、ソーシャル用の短尺など、完成した動画ファイルが必要で、一本あたり数分の待ちを許容できる。
- 長さ、解像度、音声をユーザーに選ばせたい。そしてすべての組み合わせを、確定前に値段として示す必要がある。
こんなときは別の方法へ
- 一回のリクエスト内で答えが要る場合。テキストモデルはストリームしますが、動画はしません。
- 生成途中でキャンセルしたい場合。受理されたタスクは終端状態まで走り、戻るのは未使用の保留分だけです。
裏付け
自分で確認できること
すべてのフィールドは公開スキーマ由来です
各モデルページのフォームはそのエンドポイントの input_schema から生成され、サーバーも同じ文書で検証します。宣言されていないフィールドは黙って捨てられず 400 になります。
見積もりは上限であって推測ではありません
createTask は見積額を保留し、cost と settled: false で返します。最終請求が保留額を超えることはなく、失敗や期限切れでは全額解放されます。
キーごとに使える上限を決められます
1 日・1 か月・累計の上限を設定し、使えるモデルと接続元 IP を絞り込めます。書き込み系のリクエストはすべて同じ冪等キーを受け取ります。
公開前に
確認しておくプラットフォームの挙動
- そのエンドポイントが今日呼べるか確認します。提供状況はファミリーではなくエンドポイント単位で公開されます。
- taskId と Idempotency-Key をブラウザセッションの外に、対にして保存します。
- 本文を読む前にコールバック署名を検証し、配信は繰り返される前提で組みます。
- 完成メディアは自社ストレージへ複製します。生成結果の保持は 14 日です。
よくある質問
このページでよく聞かれること
エンドポイント、指定した長さ、そのときの待ち行列によります。だからこの API は非同期です。202 をリクエストの終わり、コールバックまたは上限付きポーリングをジョブの終わりと考えてください。同期の動画エンドポイントはありません。
できません。createTask が 202 を返した時点で、タスクは終端状態まで進みます。失敗や期限切れなら保留は全額解放され、成功時の請求も保留額を超えません。
そのエンドポイントのスキーマで価格に影響すると記された項目、通常は duration_seconds、resolution、generate_audio です。確定前にその組み合わせの金額を知るには、実際の本文を見積もってください。
音声フィールドを宣言しているエンドポイントで、かつ自分でオンにした場合だけです。generate_audio はレートを変えるため、画質トグルではなく価格に影響する操作として扱われます。
モデル
この用途で呼び出せるモデル
各リンクはそのモデルシリーズのページに移動します。入力、上限、コンテンツ方針、単位あたりの現在価格をそこで確認できます。
