# Seedance 2 AI Public API

Base URL: https://seedance2ai.io/api/v1

## Authentication

```http
Authorization: Bearer sk_live_your_api_key
Content-Type: application/json
Idempotency-Key: a-unique-id-per-request
```

Create an API key in the dashboard: https://seedance2ai.io/app/api

## Rules

- Calls spend credits from the key owner's personal balance. Team credits are not used.
- Do not send teamSlug or provider — the server picks the provider automatically.
- Media URLs must be public HTTPS URLs. asset:// URLs are not accepted.
- Send an Idempotency-Key on every POST so retries never create duplicate paid tasks.
- Submitting returns a task id (sd2_… / gpt2_… / nbp_…). Poll GET /tasks/{id} until status is completed or failed.

## Seedance 2 Video — POST /api/v1/video/seedance2

| Parameter | Type | Required | Default | Allowed values |
|-----------|------|----------|---------|----------------|
| mode | string | No | text-to-video | text-to-video, image-to-video, media-to-video |
| quality_tier | string | No | standard | mini, standard, pro |
| channel | string | No | standard | standard, real, wild |
| prompt | string | Yes | — | 3–10000 characters |
| aspect_ratio | string | No | 16:9 | 1:1, 21:9, 4:3, 3:4, 16:9, 9:16, adaptive |
| duration | string | No | 5 | 4–15 (seconds) |
| resolution | string | No | 720p | 720p, 1080p, 1080p-plus, 4k (1080p-plus and 4k are pro only) |
| image_url | string (URL) | image-to-video only | — | public https URL (start frame) |
| end_image_url | string (URL) | No | — | public https URL (optional end frame) |
| media_urls | string[] (URL) | media-to-video only | — | up to 12 public https image/video URLs; video URLs must support Range duration probing |
| generate_audio | boolean | No | true | true, false |
| fixed_lens | boolean | No | false | true, false |
| seed | integer | No | — | -1 to 4294967295 (not supported on the real channel or mini tier) |

```bash
curl -X POST https://seedance2ai.io/api/v1/video/seedance2 \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-video-001" \
  -d '{
    "mode": "text-to-video",
    "quality_tier": "standard",
    "prompt": "A cinematic shot of a glass train crossing a snowy mountain bridge",
    "aspect_ratio": "16:9",
    "duration": "5",
    "resolution": "720p"
  }'
```

Submit response:

```json
{
  "id": "sd2_xxxxx",
  "status": "processing",
  "model": "seedance2",
  "quality_tier": "standard",
  "channel": "standard",
  "credits_used": 30
}
```

## Seedance Prompt Guide

Seedance prompts work best as concrete director instructions, not adjective piles. Write who is in the scene, where they are, what they do, how the camera moves, and the order of events.

### Asset mapping

- Use `image_url` for the opening frame and `end_image_url` for the closing frame.
- Use `media_urls[]` for character references, camera-motion references, style references, source videos for editing, or prior clips for extension.
- Describe each asset's role in natural language inside `prompt`. Do not put raw asset ids, `asset://` URLs, or in-app-only labels such as `@图片1` in the final API prompt.
- Set `mode` to match the assets: `text-to-video` for no assets, `image-to-video` when using `image_url`, and `media-to-video` when using `media_urls`.

### Task wording

- Reference task: "Use the supplied character reference as the lead..." or "Match the supplied camera-motion reference..."
- Edit task: "Strictly edit the supplied source video; replace X with Y while preserving Z."
- Extension task: "Continue from the supplied previous clip..." The `duration` is the added segment length.
- Combination task: "Use the supplied style reference while strictly editing the supplied source video..."

### Prompt structure

For simple scenes or single edit/extension tasks, use one compact paragraph:

```text
[task wording], [subject and asset role], [scene and action], [style and constraints]
```

For complex multi-shot scenes, use three parts:

1. Overall setup and asset roles.
2. Ordered shots: Shot 1, Shot 2, Shot 3. Prefer ordered shots over exact timestamps unless timed beats are required.
3. Style and constraints.

### Quality constraints

Include concise safeguards when relevant: high detail, cinematic quality, stable faces, natural motion, no deformation, no watermarks, no logos, no subtitles unless text is intended. For multi-person scenes, add anti-duplicate-character constraints and clear left/right positioning. For anime or non-realistic looks, explicitly anchor the visual style.

## Check Seedance Task Status — GET /api/v1/tasks/{id}

```bash
curl https://seedance2ai.io/api/v1/tasks/sd2_xxxxx \
  -H "Authorization: Bearer $SEEDANCE_API_KEY"
```

Completed response:

```json
{
  "id": "sd2_xxxxx",
  "status": "completed",
  "model": "seedance2",
  "quality_tier": "standard",
  "channel": "standard",
  "credits_used": 30,
  "credits_refunded": 0,
  "output": {
    "video_url": "https://...",
    "last_frame_url": "https://...",
    "seed": 123
  },
  "error": null,
  "created_at": "2026-06-03T10:00:00.000Z",
  "updated_at": "2026-06-03T10:03:12.000Z"
}
```

`status` is one of: `processing`, `completed`, `failed`.

## GPT Image 2 — POST /api/v1/image/gpt-image-2

| Parameter | Type | Required | Default | Allowed values |
|-----------|------|----------|---------|----------------|
| type | string | Yes | — | text-to-image, image-to-image |
| prompt | string | Yes | — | 3–20000 characters |
| resolution | string | Yes | — | 1K, 2K, 4K |
| aspect_ratio | string | Yes | — | auto, 1:1, 5:4, 9:16, 21:9, 16:9, 4:3, 3:2, 4:5, 3:4, 2:3, 2:1, 1:2, 3:1, 1:3, 9:21 |
| channel | string | No | standard | standard, economy |
| batch_count | integer | No | 1 | 1–4 |
| image_urls | string[] (URL) | image-to-image only | — | 1–10 public https URLs |

```bash
curl -X POST https://seedance2ai.io/api/v1/image/gpt-image-2 \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-gpt-image-001" \
  -d '{
    "type": "text-to-image",
    "prompt": "Editorial product photo of a transparent running shoe on chrome",
    "resolution": "1K",
    "aspect_ratio": "1:1"
  }'
```

Submit response:

```json
{
  "id": "gpt2_xxxxx",
  "status": "processing",
  "model": "gpt-image-2",
  "credits_used": 8,
  "remaining_credits": 120
}
```

When `batch_count` > 1, the response also returns `batch_task_ids`, `batch_success`, and `batch_failed`.

## Check GPT Image 2 Task Status — GET /api/v1/tasks/{id}

```bash
curl https://seedance2ai.io/api/v1/tasks/gpt2_xxxxx \
  -H "Authorization: Bearer $SEEDANCE_API_KEY"
```

Completed response:

```json
{
  "id": "gpt2_xxxxx",
  "status": "completed",
  "model": "gpt-image-2",
  "credits_used": 8,
  "credits_refunded": 0,
  "output": ["https://..."],
  "error": null,
  "created_at": "2026-06-03T10:00:00.000Z",
  "updated_at": "2026-06-03T10:01:24.000Z"
}
```

`status` is one of: `processing`, `completed`, `failed`.

## Nano Banana Pro — POST /api/v1/image/nano-banana-pro

| Parameter | Type | Required | Default | Allowed values |
|-----------|------|----------|---------|----------------|
| type | string | Yes | — | text-to-image, image-to-image |
| prompt | string | Yes | — | 3–10000 characters |
| image_size | string | No | auto | 1:1, 9:16, 16:9, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9, auto |
| output_format | string | No | png | png, jpeg |
| resolution | string | No | 1K | 1K, 2K, 4K |
| image_urls | string[] (URL) | image-to-image only | — | 1–8 public https URLs |

```bash
curl -X POST https://seedance2ai.io/api/v1/image/nano-banana-pro \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-nbp-001" \
  -d '{
    "type": "text-to-image",
    "prompt": "A premium packaging mockup for an AI video studio",
    "image_size": "1:1",
    "resolution": "1K",
    "output_format": "png"
  }'
```

Submit response:

```json
{
  "id": "nbp_xxxxx",
  "request_id": "kie_xxxxx",
  "status": "processing",
  "model": "nano-banana-pro",
  "credits_used": 12,
  "remaining_credits": 120
}
```

## Check Nano Banana Pro Task Status — GET /api/v1/tasks/{id}

```bash
curl https://seedance2ai.io/api/v1/tasks/nbp_xxxxx \
  -H "Authorization: Bearer $SEEDANCE_API_KEY"
```

Completed response:

```json
{
  "id": "nbp_xxxxx",
  "status": "completed",
  "model": "nano-banana-pro",
  "credits_used": 12,
  "credits_refunded": 0,
  "output": {
    "images": [
      {
        "url": "https://...",
        "provider_url": "https://..."
      }
    ]
  },
  "error": null,
  "created_at": "2026-06-03T10:00:00.000Z",
  "updated_at": "2026-06-03T10:01:42.000Z"
}
```

`status` is one of: `processing`, `completed`, `failed`.

## Errors

All errors share this shape:

```json
{ "error": { "code": "invalid_request", "message": "Invalid request body" } }
```

| Code | HTTP | Meaning |
|------|------|---------|
| unauthorized | 401 | Missing, invalid, or revoked API key. |
| invalid_request | 400 | Bad input or unsupported field. |
| insufficient_credits | 402 | Not enough credits on the key owner's balance. |
| rate_limited | 429 | Too many requests for this account. Retry after the Retry-After header (in seconds). |
| idempotency_conflict | 409 | Same Idempotency-Key reused with a different body, or still running. |
| service_busy | 503 | Temporary upstream or credit-concurrency issue. Retry. |
| not_found | 404 | Task does not exist or does not belong to this key owner. |
| internal_error | 500 | Unexpected server-side failure. |

## Downloadable agent skill

Download the one-file Seedance skill directly from the website:

```bash
mkdir -p ~/.claude/skills/seedance
curl -L https://seedance2ai.io/downloads/seedance-skill.md -o ~/.claude/skills/seedance/SKILL.md
```

Direct URL: https://seedance2ai.io/downloads/seedance-skill.md

## Claude Code / Codex integration prompt

Use the Seedance 2 AI Public API. Read this document, ask the user for SEEDANCE_API_KEY if missing, submit generation jobs with an Idempotency-Key header, and poll GET /tasks/{id} until status is completed or failed. Never send provider, teamSlug, or asset:// URLs.