動画生成

動画の生成には時間がかかるため、1 回の呼び出しでは動画を返しません。タスク（申し込んだあと、生成が終わってから結果を受け取る処理）として、次の 3 つの手順で使います。

接続先 URL とキーの送り方は、ほかの OpenAI 形式のエンドポイントと同じです（https://token.echohub.io/v1、Authorization: Bearer キー）。

提供中のモデルは、モデル一覧に載せています。

モデル

• 料金（1 秒あたり、または 100 万トークンあたりの単価）は、モデル一覧の各モデルのページに載せます
• 処理地域は、モデル一覧の各モデルのページに載せています。プロンプトと、参照に使う画像・動画・音声は、その地域で処理する提供元の API に渡ります（データの取り扱い）
• 指定できる項目と値は、モデルごとに違います。下の「モデルごとの指定」を見てください

呼び出しの例

MiniMax-H3 で 6 秒・768P の動画を作り、video.mp4 に保存する例です。キーは環境変数 ECHO_API_KEY に入れておきます（クイックスタート）。

# 1. 申し込む。返ってきた id を控えます
curl "https://token.echohub.io/v1/videos" \
  -H "Authorization: Bearer $ECHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "夕方の海辺を、柴犬がゆっくり歩いている",
    "seconds": 6,
    "resolution": "768P"
  }'

# 2. 進み具合を確かめる。VIDEO_ID には 1. で返った id を入れます
VIDEO_ID="task_..."
curl "https://token.echohub.io/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $ECHO_API_KEY"

# 3. status が completed になったら、ファイルを受け取る
curl -o video.mp4 "https://token.echohub.io/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $ECHO_API_KEY"

# 仮想環境を作って有効にする
python3 -m venv .venv && source .venv/bin/activate
pip install requests

import os
import time

import requests

BASE = "https://token.echohub.io/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['ECHO_API_KEY']}"}


def check(res):
    # エラーのときは、HTTP ステータスとエラー本文を表示して終わる
    if not res.ok:
        raise SystemExit(f"HTTP {res.status_code}: {res.text}")
    return res


# 1. 申し込む
video = check(requests.post(f"{BASE}/videos", headers=HEADERS, json={
    "model": "MiniMax-H3",
    "prompt": "夕方の海辺を、柴犬がゆっくり歩いている",
    "seconds": 6,
    "resolution": "768P",
})).json()
print("申し込みました:", video["id"])

# 2. 完了か失敗になるまで、15 秒ごとに進み具合を確かめる
while video["status"] in ("queued", "in_progress"):
    time.sleep(15)
    video = check(requests.get(f"{BASE}/videos/{video['id']}", headers=HEADERS)).json()
    print(video["status"], video["progress"])

if video["status"] != "completed":
    raise SystemExit(f"生成できませんでした: {video.get('error')}")

# 3. ファイルを受け取る
res = check(requests.get(f"{BASE}/videos/{video['id']}/content", headers=HEADERS))
with open("video.mp4", "wb") as f:
    f.write(res.content)
print("video.mp4 に保存しました")

import { writeFile } from "node:fs/promises";

const BASE = "https://token.echohub.io/v1";
const auth = { Authorization: `Bearer ${process.env.ECHO_API_KEY}` };

// エラーのときは、HTTP ステータスとエラー本文を表示して終わる
async function check(res) {
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  return res;
}

// 1. 申し込む
const submitted = await check(
  await fetch(`${BASE}/videos`, {
    method: "POST",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "MiniMax-H3",
      prompt: "夕方の海辺を、柴犬がゆっくり歩いている",
      seconds: 6,
      resolution: "768P",
    }),
  }),
);
let video = await submitted.json();
console.log("申し込みました:", video.id);

// 2. 完了か失敗になるまで、15 秒ごとに進み具合を確かめる
while (video.status === "queued" || video.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  const res = await check(await fetch(`${BASE}/videos/${video.id}`, { headers: auth }));
  video = await res.json();
  console.log(video.status, video.progress);
}
if (video.status !== "completed") throw new Error(`生成できませんでした: ${JSON.stringify(video.error)}`);

// 3. ファイルを受け取る
const res = await check(await fetch(`${BASE}/videos/${video.id}/content`, { headers: auth }));
await writeFile("video.mp4", Buffer.from(await res.arrayBuffer()));
console.log("video.mp4 に保存しました");

1. 申し込む

POST /v1/videos に、JSON で次の項目を送ります。

• 画像・動画・音声は、提供元のサーバーから取得できる公開 URL で渡します
• 書く場所はモデルごとに決まっています。「モデルごとの指定」と違う場所に書いた値は、使われないことがあります。長さ・解像度・画像を Seedance 2.0 が読まない場所に書いたリクエストのように、指定どおりの動画にならない書き方や料金と食い違う書き方は、Echo が受け付けません（HTTP 400。「受け付けない書き方」）
• OpenAI 形式の size（1280x720 など）は使わないでください。縦横比の指定にはならず、モデルによっては解像度として読まれたり、エラーになったりします
• MiniMax-H3 では、画像ファイルをリクエストに付けて送ることもできます。フォーム形式（multipart/form-data）で、input_reference に 1 枚だけ付けます（20 MB まで）。フォーム形式では、metadata は JSON の文字列にします。Seedance 2.0 はファイルを受け付けません（HTTP 400）。画像は URL で渡します

申し込みを受け付けると、HTTP 200 で次のような JSON が返ります。

{"id":"task_3H0YkK1PMgAiKglDcHbxqtL8WC7C247u","object":"video","model":"MiniMax-H3","status":"queued","progress":0,"created_at":1790796502}

申し込みの時点で見込みの料金を残高から差し引きます（下の「料金」）。

2. 進み具合を確かめる

GET /v1/videos/{タスクの ID} で、タスクの状態を返します。

• Echo のサーバーは、15〜30 秒ごとに提供元へ進み具合を問い合わせます。そのため、提供元で生成が終わってから completed になるまで、30 秒ほどかかることがあります。間隔が 30 秒より長くなることもあります
• 進み具合は、10〜15 秒ほど間をあけて確かめてください。Echo から完了を知らせる仕組みはありません
• 申し込みから 24 時間たっても完了しないタスクは、failed にして全額を返金します。Seedance 2.0 は、申し込みから 23 時間たっても完了しないタスクを提供元が取り消すので、そこで failed になり、全額を返金します

3. ファイルを受け取る

GET /v1/videos/{タスクの ID}/content で、完成した動画を MP4 ファイル（Content-Type: video/mp4）で返します。HEAD でファイルの大きさだけを確かめたり、Range ヘッダーで一部分だけを受け取ったりもできます。

• Echo は、生成した動画を保存しません。このパスを呼ぶたびに、提供元からファイルを取り寄せて、そのまま渡します
• 受け取れるのは、提供元がファイルを残している間だけです。期間を過ぎると HTTP 410 を返します。完了したら、すぐに受け取って保存してください

モデルごとの指定

MiniMax-H3

• フレームの指定（images、input_reference）と参照（画像・動画）は、一緒に使えません
• 参照音声は使えません（HTTP 400）
• prompt を書かないと、HTTP 400 になります

参照画像を使う例です。

{
  "model": "MiniMax-H3",
  "prompt": "画像のマグカップが、木のテーブルの上でゆっくり回っている",
  "seconds": 5,
  "resolution": "768P",
  "metadata": {
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/mug.png"}, "role": "reference_image"}
    ]
  }
}

Seedance 2.0（doubao-seedance-2-0-260128）

• 長さは seconds、解像度は metadata.resolution に書きます。最上位の resolution や duration、input_reference、プロンプトの後ろに書く --dur 5 のような指定は、Seedance 2.0 では使えません（HTTP 400。「受け付けない書き方」）
• seconds と metadata.resolution は省略せずに書いてください。省略すると、見込みの料金を 15 秒・1080p として計算するため、残高が足りずに申し込めないことがあります（生成後に実際の量で計算し直します）
• 最初のフレーム、最初と最後のフレーム、参照（画像・動画・音声）の 3 つは、一緒に使えません（提供元の仕様）
• 画像・動画・音声は URL で渡します。フォーム形式でファイルを付けると HTTP 400 になります
• 実在の人物の顔が写った画像や動画は、参照に使えません（提供元の仕様）

最初と最後のフレームを指定する例です。

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "つぼみがゆっくり開いて花が咲く",
  "seconds": 5,
  "metadata": {
    "resolution": "720p",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/first.png"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "https://example.com/last.png"}, "role": "last_frame"}
    ]
  }
}

受け付けない書き方

次の書き方は、指定どおりの動画にならなかったり、料金の計算と食い違ったりするため、Echo が申し込みの時点で断ります。HTTP 400、error.code は invalid_request で、message に正しい書き方が入ります。料金はかかりません。

• message のうち duration、frames、input_reference、--dur の部分は、実際に書いた項目の名前になります（metadata.duration、image、--rs など）
• 正しく書いたリクエストに Echo が足すのは、Seedance 2.0 の metadata.execution_expires_after（提供元で待つ時間の上限）だけです。ほかの項目は書いたとおりに提供元に届きます

料金

動画の料金は、1 秒あたり（MiniMax-H3）または 100 万トークンあたり（Seedance 2.0）の単価で決まります。トークンは、提供元が動画の量を数える単位です。単価はモデル一覧の各モデルのページに載せます。

タスクの料金は、次の順に決まります。

1. 申し込んだときに、見込みの料金を残高から差し引きます。見込みの料金は、リクエストの長さと解像度（MiniMax-H3 は参照画像の枚数と参照動画も）から計算します。残高かキーの利用上限が足りないときは、申し込めません（HTTP 403）
2. 生成が終わると、提供元が報告した実際の量で料金を計算し直し、差額を返金するか、追加で差し引きます
3. 生成に失敗したタスクと、24 時間たっても完了しないタスク（Seedance 2.0 は 23 時間）は、全額を返金します

• 申し込みの時点で断ったリクエスト（値の誤り、提供元が受け付けなかったものなど）に、料金はかかりません
• 追加で差し引く分は、残高が足りなくても差し引きます。残高がマイナスになった分は、次のチャージから差し引きます（料金とチャージ）
• コンソールの「呼び出し履歴」に、タスクごとの状態と金額を表示します（API キーと利用状況）

エラー

エラー本文は、ほかの OpenAI 形式のエンドポイントと同じ形式です（エラーと対処）。動画生成に特有のエラーは次のとおりです。

申し込みの時点で返したエラーに、料金はかかりません。

OpenAI の SDK を使う場合

• OpenAI の SDK（Python・Node.js）にも動画の関数（videos.create など）がありますが、SDK ではこれらに「Sora の API は 2026-09-24 に終了予定」という非推奨の表示が付いています。このページの例は、SDK を使わずに HTTP で呼び出します
• SDK の videos.create は、リクエストをフォーム形式（multipart/form-data）で送ります。この形式では、metadata を JSON の文字列にしないと、提供元に届きません（Python の例：extra_body={"metadata": json.dumps({"resolution": "720p"})}）

確認した情報源