# 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 Video — POST /api/v1/video/seedance

| 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 | 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 |
| duration | string | No | 5 | 4–15 (seconds) |
| resolution | string | No | 720p | 720p, 1080p |
| 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 URLs |
| 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) |

```bash
curl -X POST https://seedance2ai.io/api/v1/video/seedance \
  -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"
  }'
```

Response:

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

## 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 |
| aspectRatio | 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 |
| batchCount | integer | No | 1 | 1–4 |
| imageUrls | 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",
    "aspectRatio": "1:1"
  }'
```

Response:

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

## 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"
  }'
```

Response:

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

## Check 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": "seedance",
  "output": { "video_url": "https://..." },
  "credits_used": 30
}
```

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

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