Dreamina video generation

Dreamina is an asynchronous video task API: submit a task, get a task ID, poll for progress, and download the MP4 when it completes. One ai:video Key covers the whole flow — the gateway handles authentication, routing, billing, and storing the finished file.

Choosing a model

The model ID encodes everything you need, so you rarely have to look anything up:

dreamina-seedance-2.0-fast : 720p -ref
└──────── model family ───┘ └tier┘ └input mode┘

• Family — 2.0-fast is quicker and cheaper per second; 2.0 has better quality and is the only family offering 1080p and 4K.
• Tier — output resolution, which also sets the per-second price.
• -ref suffix — a -ref model is image-to-video and requires input_reference; without it the model is text-to-video. These are two separate model IDs, not a toggle.

Model matrix

Billed per second of video (meter video_seconds, unit: second). Pricing is not listed here — the model discovery and catalog endpoint is the authoritative source for your organization's actual rate. Models your organization has not enabled return 403.

2.0-fast:480p is the cheapest production tier; 2.0:test exists only to validate wiring and should not be used for real output.

Which one to pick

• Validating the integration → dreamina-seedance-2.0:test
• High volume, cost sensitive → dreamina-seedance-2.0-fast:480p
• Standard deliverable output → dreamina-seedance-2.0:720p
• Need a reference frame / consistent subject → switch to -ref at the same tier and pass input_reference
• 1080p / 4K → only the 2.0 family offers them

Before you start

Create a Key in the ai.tos.run console and grant it the ai:video scope:

export TOS_API_KEY="gk_YOUR_KEY"

Every request uses:

Authorization: Bearer $TOS_API_KEY

Endpoints

Both entries share task, authentication, billing, and response contracts. The dedicated entry always uses Dreamina; the OpenAI-compatible entry routes by model and is the recommended choice for new integrations.

Request parameters

The gateway validates only model and prompt — every other field is forwarded to the Dreamina upstream as-is. The table marks who handles each field, so you can tell a gateway rejection from an upstream one.

Send only model; do not include any service-selection field. The gateway picks a service from the API Key organization's routing policy and performs failover.

Fields not listed here (new upstream parameters, for example) travel with the request body untouched — the gateway neither validates nor rewrites them.

Text-to-video

curl --noproxy '*' "https://ai.tos.run/dreamina/v1/video" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2.0-fast:480p",
    "prompt": "A product showcase video with a slow dolly-in",
    "duration": 4,
    "ratio": "16:9"
  }'

Keep the id from the response — polling and downloading both use this task ID:

{
  "id": "job_123456",
  "task_id": "job_123456",
  "object": "video",
  "model": "dreamina-seedance-2.0-fast:480p",
  "status": "queued",
  "progress": 0,
  "metadata": {}
}

Image-to-video

Switch to a -ref model ID and pass one publicly reachable http:// or https:// URL in input_reference.

curl --noproxy '*' "https://ai.tos.run/dreamina/v1/video" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2.0-fast:480p-ref",
    "prompt": "Animate the subject from the reference frame into a natural product showcase",
    "input_reference": "https://example.com/product-front.png",
    "duration": 4
  }'

The reference must be:

• A string, not an array. An array returns 400 参考图片格式无效，请提供一张图片. Dreamina accepts exactly one reference image per task.
• A publicly downloadable URL. Material-library references are not supported — do not pass asset://....
• Reachable for the whole run. The upstream fetches the URL while generating; an early expiry fails the task.

The response format matches text-to-video.

OpenAI-compatible entry

The same case works against the standard /v1/videos with an identical body:

curl --noproxy '*' "https://ai.tos.run/v1/videos" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2.0-fast:480p-ref",
    "prompt": "The runner moves left to right with alternating strides and natural arm swing; no freeze frame.",
    "input_reference": "https://example.com/runner.png",
    "duration": 4
  }'

{
  "id": "97120312-8053-4c7b-b1dd-4c392dddbeb6",
  "task_id": "97120312-8053-4c7b-b1dd-4c392dddbeb6",
  "object": "video",
  "model": "dreamina-seedance-2.0-fast:480p-ref",
  "status": "queued",
  "progress": 20,
  "created_at": 1785923067,
  "expires_at": 1786527867,
  "metadata": {}
}

Polling and download

Response fields

status is the only terminal-state signal: completed or failed.

curl --noproxy '*' "https://ai.tos.run/dreamina/v1/video/job_123456" \
  -H "Authorization: Bearer $TOS_API_KEY"

{
  "id": "job_123456",
  "task_id": "job_123456",
  "object": "video",
  "model": "dreamina-seedance-2.0-fast:480p-ref",
  "status": "completed",
  "progress": 100,
  "completed_at": 1785923670,
  "metadata": {
    "url": "https://ai.tos.run/api/files/serve/generated-videos/job_123456/output.mp4"
  }
}

Downloading the result

Once complete, download the stored MP4 through the gateway and confirm the size from the actual byte count:

curl --noproxy '*' -L "https://ai.tos.run/dreamina/v1/video/job_123456/content" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -o output.mp4
wc -c < output.mp4

The content endpoint returns video/mp4. While the task is still running it returns 409 — keep polling the same task ID. On the OpenAI-compatible entry, swap the path for /v1/videos/{task_id}/content.

metadata.url also works directly as a server URL; the download size comes from the actual Content-Length response header. Output is retained for a limited window — collect it before expires_at.

Errors and retries

Related