Video generation

Generating a video takes time, so a single call does not return the video. You use it as a task (a job you submit and whose result you collect after generation finishes), in three steps.

The base URL and the way you send the key are the same as for the other OpenAI-format endpoints (https://token.echohub.io/v1, Authorization: Bearer key).

The models currently offered are listed in the model list.

Models

• Prices (per second or per 1 million tokens) are listed on each model's page in the model list
• The processing region is shown on each model's page in the model list. The prompt and the images, videos and audio used as references are passed to the provider's API that processes them in that region (Data handling)
• The fields and values you can use differ by model. See "Parameters by model" below

Example

This example makes a 6-second 768P video with MiniMax-H3 and saves it as video.mp4. Put your key in the environment variable ECHO_API_KEY first (Quickstart).

# 1. Submit. Note the id that is returned
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. Check progress. Set VIDEO_ID to the id returned in step 1
VIDEO_ID="task_..."
curl "https://token.echohub.io/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $ECHO_API_KEY"

# 3. When status is completed, download the file
curl -o video.mp4 "https://token.echohub.io/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $ECHO_API_KEY"

# Create and activate a virtual environment
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):
    # On an error, print the HTTP status and the error body, then stop
    if not res.ok:
        raise SystemExit(f"HTTP {res.status_code}: {res.text}")
    return res


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

# 2. Check progress every 15 seconds until the task completes or fails
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"Generation failed: {video.get('error')}")

# 3. Download the file
res = check(requests.get(f"{BASE}/videos/{video['id']}/content", headers=HEADERS))
with open("video.mp4", "wb") as f:
    f.write(res.content)
print("Saved to video.mp4")

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

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

// On an error, print the HTTP status and the error body, then stop
async function check(res) {
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  return res;
}

// 1. Submit
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("Submitted:", video.id);

// 2. Check progress every 15 seconds until the task completes or fails
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(`Generation failed: ${JSON.stringify(video.error)}`);

// 3. Download the file
const res = await check(await fetch(`${BASE}/videos/${video.id}/content`, { headers: auth }));
await writeFile("video.mp4", Buffer.from(await res.arrayBuffer()));
console.log("Saved to video.mp4");

1. Submit

Send the following fields as JSON to POST /v1/videos.

• Pass images, videos and audio as public URLs that the provider's servers can fetch
• Each model decides where each value goes. Values written anywhere other than the place given in "Parameters by model" may not be used. Echo refuses requests that would produce a video different from what you asked for or a price that does not match, such as a length, resolution or image written where Seedance 2.0 does not read it (HTTP 400, "Requests that are rejected")
• Do not use the OpenAI-format size (such as 1280x720). It does not set the aspect ratio; some models read it as the resolution and others return an error
• For MiniMax-H3 you can also attach an image file to the request: use the form format (multipart/form-data) and attach one file as input_reference (up to 20 MB). In the form format, write metadata as a JSON string. Seedance 2.0 does not accept files (HTTP 400); pass images as URLs

When the submission is accepted, JSON like the following is returned with HTTP 200.

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

An estimated price is deducted from your balance at submission ("Pricing" below).

2. Check progress

GET /v1/videos/{task ID} returns the state of the task.

• Echo's servers ask the provider for progress every 15–30 seconds, so it can take about 30 seconds after the provider finishes before the status becomes completed. The interval is sometimes longer than 30 seconds
• Check progress every 10–15 seconds or so. Echo does not send a notice when a task completes
• A task that has not completed 24 hours after submission is set to failed and refunded in full. For Seedance 2.0, the provider cancels a task that has not completed 23 hours after submission; it then becomes failed and is refunded in full

3. Download the file

GET /v1/videos/{task ID}/content returns the finished video as an MP4 file (Content-Type: video/mp4). You can also use HEAD to check only the file size, or the Range header to download part of the file.

• Echo does not store generated videos. Each time you call this path, Echo fetches the file from the provider and passes it to you as is
• You can download the file only while the provider keeps it. After that, HTTP 410 is returned. Download and save the file soon after the task completes

Parameters by model

MiniMax-H3

• Frames (images, input_reference) and references (images, videos) cannot be used together
• Reference audio cannot be used (HTTP 400)
• Without prompt, HTTP 400 is returned

An example with a reference image:

{
  "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)

• Write the length in seconds and the resolution in metadata.resolution. The top-level resolution, duration and input_reference, and parameters such as --dur 5 after the prompt, cannot be used with Seedance 2.0 (HTTP 400, "Requests that are rejected")
• Do not omit seconds and metadata.resolution. When they are omitted, the estimated price is calculated as 15 seconds at 1080p, so you may not be able to submit because of your balance (the price is recalculated from actual usage after generation)
• First frame, first and last frame, and references (images, videos, audio) cannot be combined (provider's specification)
• Pass images, videos and audio as URLs. Attaching a file in the form format returns HTTP 400
• Images and videos showing real people's faces cannot be used as references (provider's specification)

An example with a first and last frame:

{
  "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"}
    ]
  }
}

Requests that are rejected

Echo refuses the following at submission, because the video would not match what you asked for, or the price would be calculated from different values than the ones used to generate the video. They return HTTP 400 with error.code invalid_request, and message says how to write the request instead. They are free.

• In message, duration, frames, input_reference and --dur are replaced with the name you actually wrote (metadata.duration, image, --rs and so on)
• For a correctly written request, the only thing Echo adds is metadata.execution_expires_after for Seedance 2.0 (the maximum time to wait at the provider). Everything else reaches the provider as written

Pricing

Video is charged at a unit price per second (MiniMax-H3) or per 1 million tokens (Seedance 2.0). Tokens are the unit the provider uses to count the amount of video. Unit prices are listed on each model's page in the model list.

The price of a task is settled in this order.

1. When you submit, an estimated price is deducted from your balance. The estimate is calculated from the requested length and resolution (for MiniMax-H3, also the number of reference images and any reference video). If your balance or the key's spending limit is not enough, the submission is refused (HTTP 403)
2. When generation finishes, the price is recalculated from the actual usage the provider reports, and the difference is refunded or additionally deducted
3. Tasks that fail, and tasks that have not completed 24 hours after submission (23 hours for Seedance 2.0), are refunded in full

• Requests refused at submission (wrong values, requests the provider did not accept and so on) are free
• An additional deduction is made even if your balance is not enough. The part that makes your balance negative is deducted from your next top-up (Pricing and top-ups)
• The state and price of each task are shown in 「呼び出し履歴」 (Call history) in the console (API keys and usage)

Errors

Error bodies use the same format as the other OpenAI-format endpoints (Errors). Errors specific to video generation are listed below.

Errors returned at submission are free.

Using the OpenAI SDK

• The OpenAI SDKs (Python, Node.js) also have video functions (videos.create and so on), but in the SDKs they are marked as deprecated with the note "The Sora API is scheduled to permanently shut down on September 24, 2026". The examples on this page call the API over HTTP without the SDK
• The SDK's videos.create sends the request in the form format (multipart/form-data). In this format, metadata does not reach the provider unless it is a JSON string (Python example: extra_body={"metadata": json.dumps({"resolution": "720p"})})

Sources