Media tasks and workflows API reference

Full reference for BigModel.io image, video, avatar, speech, music, sound-effect and short-drama workflow endpoints: request fields, the task object, statuses, errors and billing.

On this page
  1. Endpoints
  2. Headers
  3. Create fields
  4. The task object
  5. Estimates (dry_run)
  6. Workflows
  7. Errors
  8. Billing
  9. Related

Every endpoint uses Authorization: Bearer $BIGMODEL_API_KEY with base URL https://bigmodel.io/v1.

#Endpoints

Method Path Description
POST /v1/images/generations Text to image, synchronous
POST /v1/images/edits Edit, upscale, remove background, synchronous (multipart or JSON)
POST /v1/videos Create a video, avatar or video-tool task
GET /v1/videos/{id} Get a task
GET /v1/videos/{id}/content Redirect to the output (302)
POST /v1/videos/{id}/cancel Cancel a task
POST /v1/audio/speech Speech; returns audio bytes on success
GET /v1/audio/voices System voices
POST /v1/audio/generations Create a music, sound-effect or audio-tool task
GET /v1/audio/generations/{id} Get a task
GET /v1/audio/generations/{id}/content Redirect to the output (302)
POST /v1/audio/generations/{id}/cancel Cancel a task
POST /v1/workflows/short-drama Create a short-drama workflow
GET /v1/workflows/{id} Get a workflow
POST /v1/workflows/{id}/cancel Cancel a workflow

#Headers

Header Description
Idempotency-Key Optional, up to 200 characters. Repeating a value with the same key returns the first task instead of generating and charging again.
Content-Type: application/json Create requests are JSON. Media inputs are https:// URLs or base64 data URIs; bodies up to 80 MB (workflows 1 MB).

#Create fields

Field Applies to Description
model all Required model ID.
prompt video, avatar, music, sfx Text description; music style and sound-effect descriptions go here too.
image / first_frame video, avatar First frame or person image. Required for video models.
last_frame video Last frame, for first/last-frame models.
reference_images, reference_videos, reference_audios video Reference arrays, for models that take references.
seconds / duration video, sfx Output length in seconds within the model's range; default 5.
resolution video e.g. 480p, 720p, 1080p, 2k, 4k, depending on the model.
aspect_ratio / size video 16:9, 9:16, 1:1, or a size such as 1280x720.
audio video Native audio on or off, where supported.
seed video Random seed.
video avatar, video tools, audio tools Source or motion video.
input_audio avatar Speech or song that drives the lips.
target_resolution video upscale 1080p (default) or 2k.
mode clay render clay, clay_masked (default), sculpt.
keep_audio clay render Keep the source soundtrack.
isolate_voice, transcribe audio extract Separate vocals; return a transcript.
input speech Text to read, up to 4,000 characters.
voice speech Voice ID from GET /v1/audio/voices.
speed speech 0.5–2.
emotion speech happy, sad, angry, fearful, disgusted, surprised, calm, fluent, whisper.
lyrics, instrumental music Lyrics; instrumental only.
dry_run all create requests true returns an estimate without generating.

#The task object

json
{
  "id": "9abb6ad1-167a-43b2-a4cd-95c712c11969",
  "object": "video",
  "model": "seedance-2.0-mini",
  "status": "succeeded",
  "progress": 100,
  "created_at": 1760000000,
  "completed_at": 1760000111,
  "estimated_cost_usd": 0.0823,
  "cost_usd": 0.0823,
  "output": {"type": "video", "url": "https://bigmodel.io/v1/media/…", "expires_in": 86400}
}
Field Description
object video or audio.generation.
status queued, running, succeeded, failed, canceled.
progress 0–100, reported by some models while running.
estimated_cost_usd Estimate reserved when the task was created.
cost_usd Final charge, on succeeded tasks.
output.url Signed output link, valid 24 hours; get the task again for a new one.
error.message Why it failed.

POST /v1/audio/speech returns the audio itself (Content-Type: audio/mpeg) with the task ID in X-Task-Id. If it isn't done within 85 seconds you get 202 and the task object; then use GET /v1/audio/generations/{id}.

#Estimates (dry_run)

json
{"object": "quote", "model": "seedance-2.0", "unit": "per_second", "estimated_units": 10, "estimated_cost_usd": 0.66}

#Workflows

Fields and the result object are in Short-drama workflow.

#Errors

Status error.type Meaning
400 invalid_request_error A parameter doesn't fit the model; message says why.
401 authentication_error Invalid key.
402 insufficient_balance Balance can't cover the estimate (including reserves for unfinished tasks).
404 model_not_available Your key's group doesn't offer the model, or the model belongs to another endpoint.
404 not_found_error The task doesn't exist or isn't yours.
409 not_ready Output requested before the task finished.
503 api_error Temporarily unavailable; retrying with an Idempotency-Key is safe.

#Billing

  • Images: per image returned.
  • Video, avatars, video tools: per output second. Speech: per character or audio second. Music and sound effects: per call. Audio extraction: per video second.
  • Charged when the task succeeds and shown in the console's Logs; failed and cancelled tasks are free.
  • The estimate is reserved at creation; if your balance minus all unfinished reserves is short, you get 402.

Updated · View as Markdown