# 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.

Web version: https://bigmodel.io/docs/api-media-tasks · Updated 2026-10-18

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](https://bigmodel.io/docs/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`.

## Related

- [Multimodal overview](https://bigmodel.io/docs/multimodal-overview)
- [Short-drama workflow](https://bigmodel.io/docs/short-drama-workflow)