生成

動画・画像モデルの生成には数秒から数分かかるため、リクエストはすべて非同期です。送信すると、すぐに生成情報が返されます。最終状態に達するまでポーリングするか、Webhookを受信してください。生成オブジェクトにはジョブ全体の入力、状態、出力、エラー、料金が含まれます。

ライフサイクル#

succeeded、failed、canceledは最終状態です。いずれかに達した後、生成の状態は変わりません。中間状態が追加された場合にも動作するよう、ほかの値は「処理中」として扱ってください。

1. 送信#

モデルの入力項目をJSON本文として指定してPOST /api/v1/run/{endpoint}を送信します。エンドポイントIDにはモデルとタスクが含まれます。例：bytedance/seedance-2.0-fast/text-to-video。すべてのエンドポイントと入力項目はモデルページに掲載されています。

入力を検証して料金を計算し、残高から料金を確保してジョブをキューに追加します。レスポンスは202 Acceptedで、生成情報に加えて便利なurls.getとurls.cancelも返します：

{
  "id": "gen_8c2QmX1nq0k4Lw7Z",
  "object": "generation",
  "model": "bytedance/seedance-2.0-fast",
  "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
  "mode": "text-to-video",
  "status": "queued",
  "input": {
    "prompt": "ゴールデンアワーの光の中、陶芸家が花瓶を形作る様子をゆっくり寄って撮影。光に浮かぶほこり、浅い被写界深度。",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true
  },
  "output": null,
  "error": null,
  "cost": {
    "amount_usd": 0.4494,
    "currency": "usd",
    "estimated": true
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04.512Z",
  "started_at": null,
  "completed_at": null,
  "retention": "1d",
  "expires_at": null,
  "purged_at": null,
  "urls": {
    "get": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z",
    "cancel": "https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel"
  }
}

参照画像・動画・音声#

reference-to-videoモードでは、最大3種類の参照素材を指定できます。各項目にはHTTPS URL（公開リンク、またはアップロードから取得したURL）の一覧を渡します：reference_image_urlsはキャラクター、商品、シーン用、reference_video_urlsは動き、カメラワーク、効果用、reference_audio_urlsは声、音楽、音声用です。

プロンプトでは位置を指定して参照します：@Image1はreference_image_urls内の最初のURL、@Video1はreference_video_urls内の最初のURL、@Audio2は2つ目の音声クリップを示します。以降も同様です。大文字・小文字を区別せず@Image1に正規化します。一致する素材がない指定（例：動画を1本添付した状態で@Video2を指定）は400 invalid_request（param: "prompt"）で拒否され、料金は発生しません。

{
  "prompt": "@Image1 dances on a rooftop, copying the choreography and camera move of @Video1, in sync with @Audio1",
  "reference_image_urls": [
    "https://example.com/dancer.jpg"
  ],
  "reference_video_urls": [
    "https://example.com/choreo.mp4"
  ],
  "reference_audio_urls": [
    "https://example.com/beat.mp3"
  ],
  "resolution": "720p",
  "duration": 8
}

送信時に参照動画・音声ファイルの先頭部分をダウンロードし、長さ、サイズ、解像度、フレームレートを実測してモデルの上限と照合します。20秒のクリップ、720pまでのモデルに渡す1080p動画、MP3またはWAV指定時のM4A、応答しないURLなど、範囲外の入力には400 invalid_requestが返され、paramに対象フィールド（例：reference_video_urls）が設定されます。料金発生前にクリップ名を示すメッセージも返します。参照動画の秒数は課金対象です。詳しくはお支払いをご覧ください。

動画はH.264またはH.265形式のMP4/MOVである必要があります。上限にはモデルが実行される処理容量のうち最も厳しい値が適用されるため、ここで受け付けられたリクエストは上流でも処理されます。参照画像や音声によって料金が変わることはありません。

2. 結果をポーリング#

GET /api/v1/generations/{id}は現在の状態を返します。生成情報の読み込み時、ステータス確認の時刻になっていれば先に確認するため、ポーリング結果は数秒以上古くなりません。

const API = "https://cheapergen.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}` };
const FINAL = new Set(["succeeded", "failed", "canceled"]);

export async function wait(id, timeoutMs = 15 * 60_000) {
  let delay = 2000;
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const gen = await fetch(`${API}/generations/${id}`, { headers }).then((r) => r.json());
    if (FINAL.has(gen.status)) return gen;
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 10_000); // back off to every 10 s
  }
  // Giving up: cancel it first, or it still runs and is charged when it finishes (once running it can't be: 409).
  await fetch(`${API}/generations/${id}/cancel`, { method: "POST", headers }).catch(() => {});
  throw new Error(`Timed out waiting for ${id}`);
}

import os, time, requests

API = "https://cheapergen.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"}

def wait(gen_id, timeout=900):
    delay, waited = 2, 0
    while waited < timeout:
        gen = requests.get(f"{API}/generations/{gen_id}", headers=headers).json()
        if gen["status"] in ("succeeded", "failed", "canceled"):
            return gen
        time.sleep(delay)
        waited += delay
        delay = min(delay * 1.5, 10)  # back off to every 10 s
    # Giving up: cancel it first, or it still runs and is charged when it finishes (once running it can't be: 409).
    requests.post(f"{API}/generations/{gen_id}/cancel", headers=headers)
    raise TimeoutError(gen_id)

推奨するポーリング間隔#

• 画像： 1〜2秒ごとに確認します。ほとんどのタスクは30秒以内に完了します。
• 動画： 最初は3〜5秒ごとに確認し、その後は徐々に10秒間隔まで延ばします。5秒の動画は通常1〜3分で完成し、高解像度ではさらに時間がかかります。
• ポーリングはレート制限の上限に含まれます。ジョブを多数同時に実行する場合はWebhookがおすすめです。

3. 出力を利用#

成功するとoutputに生成メディアのHTTPS URLが含まれます。動画モデルは1つのファイルを返します：

{
  "output": {
    "video": {
      "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
      "content_type": "video/mp4"
    }
  }
}

画像モデルは生成した画像ごとに1件ずつ、リストで返します：

{
  "output": {
    "images": [
      {
        "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.png",
        "content_type": "image/png"
      }
    ]
  }
}

失敗と返金#

生成に失敗した場合、 status は failed、error は原因と対処方法を示し、 cost.amount_usd は 0 — 確保額は全額残高に返金されます。モデル提供元の障害やエラーでは、ジョブを失敗と判定する前に、条件を満たすほかのすべてのルートで自動的に再試行します。安全フィルターによる拒否や、モデルが受け付けない入力は再試行しません。同じリクエストは再び拒否されるためです。モデル提供元が入力ファイルをダウンロードできない場合、通常は当社側でダウンロードしてコピーを使って再試行します。料金は変わりません。input_unreachableは多くの場合、ファイルをまったくダウンロードできなかったことを意味します。

{
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "ByteDance's safety review for Seedance 2.0 Fast rejected this request (the prompt or an input file).",
    "reason": "content_blocked",
    "hint": "Describe the character's look instead of naming a copyrighted character or real person, keep it non-explicit, or try another model.",
    "retryable": false,
    "refunded": true,
    "detail": "リクエストがコンテンツ安全性チェックを通過しませんでした。プロンプトを修正して、もう一度お試しください。"
  },
  "cost": {
    "amount_usd": 0,
    "currency": "usd",
    "estimated": false
  }
}

• code — 提供開始以来変わらない大分類：generation_failed（入力が拒否された、または処理を完了できなかった）、upstream_error、timeout、model_unavailable。
• reason — 下表に記載する具体的な理由です。新しい連携ではこの値に基づいて処理してください。理由が追加される場合があります。
• message — ユーザーに表示できる、発生した問題の説明です。安全フィルターが拒否した場合は、どのモデル提供元のフィルターかも示します。
• hint — 次に変更または実行する内容です。
• retryable — trueは同じリクエストの再送で成功する可能性があり、falseは同じ理由で失敗することを示します。
• refunded — trueは確保額が返金されたことを示します。失敗した生成に料金はかかりません。
• param — 変更する入力項目。判定できる場合に示します（例：image_url、duration）。
• detail — 情報の補足に役立つ場合に記録する、モデル提供元の文言です。

reasonが存在する前に失敗した生成には、元のcodeを保持します。reasonとhintも設定されます。

緊急時の料金#

通常の処理容量を利用できない場合、より高価な容量で実行することがあります。その場合の料金は 緊急時の料金、モデルの公式価格を超えることはありません。 allow_fallback_price の適用条件を決め、デフォルトは true REST APIとMCPでは、新しいリクエストの見積もりと請求に緊急時の料金が適用されます。また、標準料金で受け付けたジョブの処理容量が途中で利用できなくなった場合も、緊急時の料金に切り替えることがあります（その時点で追加額を確保します）。 max_cost_usd は両方に上限を適用します。次を送信： allow_fallback_price: false 見積もり価格を超えて支払わないよう設定できます（ ProまたはMaxプラン。受け付け済みジョブの価格が変わる場合もありますが、上限は通常価格です）：新しいリクエストには503 fallback_price_declinedが適用され、受け付け済みジョブでは料金を引き上げずに失敗として全額返金します。Studioのジョブは、実行ボタンを押した後に高い料金へ切り替わりません。適用された場合は、生成情報の pricing.fallback （Webhookにも含まれます）にその旨と両方の料金が記録されます。が適用されます。

安全性チェッカー#

enable_safety_checkerの既定値はtrueです。APIではfalseを送信できます。Studioとモデルページでは常にオンになっています。機能はモデルによって異なります。

• クローズドモデル （Seedance、Kling、Veo、MiniMax H3、Wan 3.0など）には、無効化できない各ラボ独自のモデレーション機能があります。受け付けるのは true と falseではどちらも挙動が変わらないため、スキーマにこのオプションはありません。例外としてMiniMax H3 Maxはフィルターをオフに切り替えられるため、スキーマにこのオプションが含まれます。そのリクエストには個別の安全設定が適用されます — 緊急価格が適用される場合もありますが、公式価格を超えることはありません。
• Seedream 4.5 and Seedream 5.0 Liteにもそのオプションがあります。オフにすると、リクエストはByteDance独自の海外向けモデル構成で実行され、追加フィルターは適用されません。オンにすると通常のフィルターが適用されます。当社のチェックでは、未成年者が関わる性的なコンテンツは引き続きブロックされます。オフにしたリクエストには別途、高い料金Seedream 4.5 $0.04 per image · Seedream 5.0 Lite $0.035 per imageが適用されます。/quoteはenable_safety_checker: false （ fallback.reason "safety_checker_off"を送信すると返します。これは緊急時の料金として扱われ、allow_fallback_price: falseの場合、このリクエストは拒否されます。すぐに実行できない場合は503 model_unavailable（param: "enable_safety_checker"）で拒否されます。標準フィルターを使って実行するにはtrueを送信してください。
• オープンウェイトモデルではオプションが表示されます。独自のフィルターがない処理枠で生成する場合、当社のチェック機能がプロンプトと入力画像を事前に確認します。スイッチがオンの場合は性的な内容、露骨な暴力、自傷行為に関する内容をブロックし、オフの場合でも未成年者が関わる性的な内容はブロックします。独自の切り替え可能なフィルターがある処理枠では、送信された設定をそのまま渡します。フィルターがオフの場合でも、当社のチェック機能は未成年者が関わる性的な内容をブロックします。

false：オプションが表示されず、チェック機能を無効にできないモードに指定すると、400 invalid_requestが返されます。オフにしても、当社の許容利用ポリシーで禁止されている内容は許可されません。

データの保存期間#

APIで生成したコンテンツはデフォルトで、生成完了から1日の間保持されます。その後、プロンプト、入力メディア、出力と関連ファイルを自動削除します。生成履歴自体はモデル、料金を決めるパラメーター、料金、タイムスタンプを保持するため、利用履歴と請求書を正確に保てます：outputがnullになり、purged_atが設定され、content_expiredが削除理由を示します。保存したい出力はexpires_atより前にダウンロードしてください。

リクエスト本文にretentionを渡すと、生成ごとに保存期間を選べます。すべてのアカウントで短縮でき、最大1dまで延長できます。7dと30dの設定にはアカウント単位の保存期間設定が必要です。営業にお問い合わせください。アカウントで許可される期間を超えると400 invalid_requestとparam: "retention"が返されます。

{
  "prompt": "A paper boat drifting down a rain-soaked street",
  "resolution": "720p",
  "duration": 5,
  "retention": "immediate",
  "webhook_url": "https://example.com/hooks/cheapergen"
}

Studioとプレイグラウンドでの生成は削除するまで保持されます。アップロードは保存中の生成から使用されている間保持し、どの生成からも使われないファイルは1日後に削除します。アカウント削除時には生成とファイルもすべて削除されます。モデル提供元に保存期間の選択肢がある場合、提供元側での保存も最短にするよう依頼します。

生成を削除する#

完了した生成は、DELETE /api/v1/generations/{id}、ダッシュボードの生成一覧、またはStudioのビューアーから削除できます。APIでは、まだキャンセルできるキュー内の生成も削除できます（先にキャンセルされ、確保された料金は全額返金されます）。ファイル、プロンプト、入力はすぐに削除され、一覧からも消えます。請求額は請求履歴に残ります。詳しくはAPIリファレンスをご覧ください。

キャンセル#

POST /api/v1/generations/{id}/cancelはまだqueuedの生成をキャンセルし、確保額を返金します。ジョブがrunningになるとモデルが処理を開始しているため、キャンセルすると409 conflictが返り、ジョブは通常どおり完了・課金されます。キューに追加された後はキャンセルできないモデルもあります。その場合も409が返ります。

curl -X POST https://cheapergen.com/api/v1/generations/gen_8c2QmX1nq0k4Lw7Z/cancel \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

生成一覧を取得する#

GET /api/v1/generationsは生成を新しい順にカーソルページネーションで返します。次の条件で絞り込めます：status、model、source（playground、api、mcp）。返されたnext_cursorをcursorとして渡すと次のページを取得できます。詳細はAPIリファレンスをご覧ください。

curl "https://cheapergen.com/api/v1/generations?status=succeeded&limit=50" \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Studioやモデルページのプレイグラウンドで作成した生成もここに表示され、source: "playground"が付きます。APIリクエストにはsource: "api"が付きます。