Video Generation

Overview

Generate video asynchronously from a text prompt (or a first-frame image). Because generation takes a while, it is a two-step, submit-then-poll flow: POST to submit a task and get a task_id, then poll by task_id until the status becomes completed.

Request Parameters

Submit a Task

On success the API returns a task object with status queued. Record the id (the task_id) for the follow-up query.

curl -X POST "https://www.starunion.net/v1/video/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "A silver wolf running across a moonlit snowfield, cinematic shot",
    "duration": 5,
    "resolution": "1080p",
    "ratio": "16:9",
    "generate_audio": true
  }'

{
  "id": "video_7xN3f2k...",
  "task_id": "video_7xN3f2k...",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "queued",
  "progress": 0,
  "created_at": 1708502400
}

Fetch the Result

Poll the task status with the task_id from the submit step. The status moves through queued → in_progress → completed (or failed). Poll every 5–10 seconds; once completed, the video URL is in metadata.url.

curl "https://www.starunion.net/v1/video/generations/video_7xN3f2k..." \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "video_7xN3f2k...",
  "task_id": "video_7xN3f2k...",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "completed",
  "progress": 100,
  "created_at": 1708502400,
  "completed_at": 1708502460,
  "metadata": {
    "url": "https://cdn.starunion.net/videos/abc123.mp4"
  }
}

OpenAI-compatible Endpoints

Besides /video/generations above, the platform exposes a set of endpoints shaped exactly like the OpenAI Videos API: create, retrieve, download and remix. Both sets share the same models, channels and billing; only the response shape differs — this set always returns an OpenAI video object (object is always video), so the data structures of the OpenAI SDK can be reused as-is.

• POST /videos — create a generation task
• GET /videos/{id} — retrieve task status and result
• GET /videos/{id}/content — download the video file
• POST /videos/{id}/remix — regenerate from an existing task

Create a Video (/videos)

The request body accepts application/json, multipart/form-data and application/x-www-form-urlencoded. Fields not listed below are forwarded to the upstream model untouched, so vendor-specific parameters can be written exactly as in the vendor's own docs.

curl -X POST "https://www.starunion.net/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A silver wolf running across a moonlit snowfield, cinematic shot",
    "seconds": "4",
    "size": "1280x720"
  }'

{
  "id": "video_7xN3f2k...",
  "task_id": "video_7xN3f2k...",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1708502400
}

Retrieve a Video (/videos)

status moves through queued → in_progress → completed (or failed); a task that has just been stored but not yet dispatched briefly returns unknown. Poll every 5–10 seconds; on failure error.message carries the reason. Tasks are scoped to the account owning the API key — someone else's task, or an unknown id, both return 400 task_not_exist.

curl "https://www.starunion.net/v1/videos/video_7xN3f2k..." \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "video_7xN3f2k...",
  "task_id": "video_7xN3f2k...",
  "object": "video",
  "model": "sora-2",
  "status": "completed",
  "progress": 100,
  "created_at": 1708502400,
  "completed_at": 1708502460,
  "seconds": "4",
  "size": "1280x720"
}

Download the File

Returns the raw video stream. The platform fetches it from the origin on your behalf, so the upstream address and its signature are never exposed to the client. The response carries Cache-Control: public, max-age=86400 and can be used directly as the src of a <video> element. A task that has not completed yet returns 400.

curl "https://www.starunion.net/v1/videos/video_7xN3f2k.../content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o output.mp4

Remix

Regenerate from an already submitted task with a new prompt. The body only needs prompt — model, resolution and duration are inherited from the original task, and the same channel is reused so the style stays consistent.

curl -X POST "https://www.starunion.net/v1/videos/video_7xN3f2k.../remix" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Same wolf, now backlit at dusk, with a slow push-in"
  }'

{
  "id": "video_9pQ8h1m...",
  "task_id": "video_9pQ8h1m...",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1708502500,
  "remixed_from_video_id": "video_7xN3f2k..."
}