# Seedance 2.0 Video API Reference

Create Seedance 2.0 text-to-video and image-to-video tasks from your app, backend, or automation workflow.

> Production Beta: the v1 endpoint is callable. This first public version supports text-to-video and image-to-video only.

## Base URL

```text
https://imya.ai
```

## Authentication and idempotency

Create an API key in your imya account and pass it as a Bearer token. Every generation POST also requires an idempotency key.

```http
Authorization: Bearer imya_xxxxxxxxx
Content-Type: application/json
Idempotency-Key: your-unique-request-id
```

Use a new idempotency key for each logical generation request. Retrying the same request with the same key returns the original task instead of creating and charging for another task. Keys may contain 1-128 ASCII letters, numbers, dots, colons, underscores, or hyphens.

## Create a video generation task

```http
POST /v1/videos/generations
```

### Supported workflows

| Mode | Image input | Notes |
| --- | --- | --- |
| `text-to-video` | Not accepted | May enable `web_search`. |
| `image-to-video` | `image_url` is required | May include `last_frame_url`. |

Reference-to-video, video editing, and multi-reference workflows are not part of this first public API version.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| model | string | Yes | Use `seedance-2.0`. |
| mode | string | Yes | `text-to-video` or `image-to-video`. |
| prompt | string | Yes | Generation instructions, from 3 to 20,000 characters. |
| image_url | string | Conditional | Public HTTPS first-frame image. Required for image-to-video and not accepted for text-to-video. |
| last_frame_url | string | No | Optional public HTTPS last-frame image for image-to-video only. |
| duration | number | No | Integer from `4` to `15` seconds. Default is `5`. |
| resolution | string | No | `480p`, `720p`, or `1080p`. Default is `720p`. |
| aspect_ratio | string | No | `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`, or `adaptive`. Default is `16:9`. |
| generate_audio | boolean | No | Generate audio with the video. Default is `true`. |
| web_search | boolean | No | Enable web search for text-to-video. Default is `false`; not accepted for image-to-video. |

### Text-to-video example

```bash
curl https://imya.ai/v1/videos/generations \
  -H "Authorization: Bearer YOUR_IMYA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seedance-t2v-order-001" \
  -d '{
    "model": "seedance-2.0",
    "mode": "text-to-video",
    "prompt": "A quiet coastal train passing cliffs at sunrise, smooth aerial tracking shot",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "web_search": false
  }'
```

### Image-to-video example

```bash
curl https://imya.ai/v1/videos/generations \
  -H "Authorization: Bearer YOUR_IMYA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seedance-i2v-order-001" \
  -d '{
    "model": "seedance-2.0",
    "mode": "image-to-video",
    "prompt": "Subtle wind moves the fabric while the camera arcs slowly to the right",
    "image_url": "https://cdn.example.com/input/first-frame.jpg",
    "last_frame_url": "https://cdn.example.com/input/last-frame.jpg",
    "duration": 8,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'
```

### Accepted response

```json
{
  "id": "task_0123456789abcdef0123456789abcdef",
  "status": "pending",
  "model": "seedance-2.0",
  "credits_reserved": 625
}
```

The example number illustrates the response shape only. `credits_reserved` is calculated for the current request and account at submission time; do not calculate or cache the charge in your client.

## Retrieve a task

```http
GET /v1/tasks/{task_id}
```

Poll no faster than once every 5 seconds.

### Example request

```bash
curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer YOUR_IMYA_API_KEY"
```

### Completed response

```json
{
  "id": "task_0123456789abcdef0123456789abcdef",
  "status": "succeeded",
  "model": "seedance-2.0",
  "credits_used": 625,
  "data": [
    {
      "url": "https://media.example.com/generated/example.mp4"
    }
  ]
}
```

Video result URLs may be temporary. Download successful results promptly. Production Beta does not yet guarantee 7-day or 30-day retention for API video results.

## Status values

| Status | Meaning |
| --- | --- |
| pending | The task has been accepted. |
| processing | The model is generating. |
| succeeded | The result is ready. |
| failed | The task failed. Inspect the sanitized `error` object. |

New tasks return HTTP `202`. Replaying the same request and idempotency key returns HTTP `200` with `Idempotent-Replayed: true`. Task retrieval returns HTTP `200`; a failed task may report `generation_failed`, `refund_pending`, or `media_deleted` in `error.code`.

## Credit billing

The server calculates the live charge from the selected mode, resolution, duration, and the API key owner's current plan. The POST response returns that charge as `credits_reserved`. A successful task reports the final debit as `credits_used`.

Do not hard-code a Seedance credit price in your application. Failed tasks release or refund eligible reserved credits once without extending the original expiration date of promotional or reward credits.

## Errors

| Code | Meaning |
| --- | --- |
| 400 | Missing or invalid idempotency key or malformed JSON. |
| 401 | Missing or invalid API key. |
| 402 | Not enough credits. |
| 403 | The API account is disabled. |
| 409 | The idempotency key was already used with a different request body. |
| 413 | The request body exceeds 64 KiB. |
| 422 | Invalid mode, prompt, media URL, duration, resolution, or aspect ratio. |
| 429 | Rate or concurrent-task limit reached. |
| 5xx | The request could not be completed or submitted. |