# Seedance 2.0 Public API

Base URL: https://seedancetovideo.com/api/v1
Contract version: 1.0.0
OpenAPI: https://seedancetovideo.com/openapi.json

## Authentication

Send a server-side API key on every request:

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

Create and revoke keys at https://seedancetovideo.com/settings/apikeys. Full keys are shown once and stored only as SHA-256 digests. Never expose a key in browser or mobile client code.

## Rules

- API calls spend only the key owner's paid personal credits. Promotional credits are excluded.
- The exact paid-credit amount is atomically reserved before any remote media download starts. Failures confirmed before provider acceptance refund the reservation and delete inputs uploaded during that attempt. If provider acceptance is uncertain, the task, credits, and managed inputs remain held for reconciliation; retry only with the same Idempotency-Key and never create a new key for that request.
- The server selects the generation provider. Do not send a provider parameter.
- Every POST requires a unique Idempotency-Key header.
- Reference assets must be reachable public HTTPS URLs and all input media combined must not exceed 256 MB. Each redirect and resolved address is checked; payloads are type/size validated and copied to managed storage before provider submission.
- Reference videos are fully decoded so the server can measure duration and dimensions. Billing uses the measured reference-video duration and requested output resolution, never untrusted container metadata.
- The rate limit is 30 authenticated requests per 60 seconds per API key.
- Submit returns an asynchronous task. Poll GET /tasks/{id} until completed or failed.
- Public API tasks do not receive an early timeout refund while the provider is still processing. Eligible terminal failures, unstarted tasks, and expired tasks are refunded.
- A task is marked completed only after its provider output has been copied to Seedance-managed storage.
- Hosted output URLs are delivery URLs, not permanent archival storage. Copy completed outputs promptly.
- The v1 contract is stable at /api/v1. Incompatible changes use a new versioned base path and are published in the developer documentation.

## Create a Seedance video

POST https://seedancetovideo.com/api/v1/video/generations

Fields:

- mode: text-to-video | image-to-video | media-to-video (default text-to-video)
- model: seedance-2.0 | seedance-2.0-fast | seedance-2.0-mini (default seedance-2.0-fast)
- prompt: required string, 3-4000 characters
- aspect_ratio: 1:1 | 21:9 | 4:3 | 3:4 | 16:9 | 9:16 | adaptive (default 16:9)
- duration: 4-15 seconds (default 5)
- resolution: model-dependent; 480p or 720p on all public models, plus 1080p and 4k on seedance-2.0
- image_url: public HTTPS opening frame, required for image-to-video
- end_image_url: optional public HTTPS closing frame
- reference_image_urls: up to 8 public HTTPS URLs
- reference_video_urls: up to 3 public HTTPS URLs; each must be 2-15 seconds with a 480p-720p short side, and their combined duration must not exceed 15 seconds
- reference_video_durations: required when reference_video_urls is present; provide one whole-second value per URL for pre-download credit reservation, and each value must match the fully decoded server measurement
- Reference-audio input is not available in public API v1.
- generate_audio: boolean (default true)
- seed: integer from -1 through 4294967295

Mode combinations:

- text-to-video accepts no media fields.
- image-to-video accepts image_url and optional end_image_url only.
- media-to-video accepts typed reference_* fields only and requires at least one reference image or video.

Example:

```bash
curl -X POST https://seedancetovideo.com/api/v1/video/generations \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-demo-001" \
  -d '{
    "mode": "text-to-video",
    "model": "seedance-2.0-fast",
    "prompt": "A cinematic glass train crossing a snowy mountain bridge",
    "aspect_ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'
```

The response uses HTTP 202 for a new task and HTTP 200 when an idempotent retry returns an existing task.

## Query a task

GET https://seedancetovideo.com/api/v1/tasks/{id}

```bash
curl https://seedancetovideo.com/api/v1/tasks/idem_xxxxx \
  -H "Authorization: Bearer $SEEDANCE_API_KEY"
```

Task status is processing, completed, or failed. A completed task includes output.video_url. Failed eligible tasks report credits_refunded.

## Query paid credit balance

GET https://seedancetovideo.com/api/v1/credits

## Standard credit pricing per output second

| Model | 480p | 720p | 1080p | 4k |
|---|---:|---:|---:|---:|
| seedance-2.0 | 30 | 60 | 150 | 350 |
| seedance-2.0-fast | 25 | 50 | - | - |
| seedance-2.0-mini | 15 | 30 | - | - |

## Reference-video credit pricing

When reference videos are used, billing is:

(output seconds + server-measured reference-video seconds) x reference rate

| Model | 480p | 720p | 1080p | 4k |
|---|---:|---:|---:|---:|
| seedance-2.0 | 20 | 40 | 100 | 200 |
| seedance-2.0-fast | 15 | 30 | - | - |
| seedance-2.0-mini | 10 | 20 | - | - |

Example: seedance-2.0-fast at 720p with 5 seconds of output and 3 seconds of reference video costs (5 + 3) x 30 = 240 credits.

## Errors

Errors use this envelope:

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

Codes: unauthorized (401), invalid_request (400), insufficient_credits (402), not_found (404), idempotency_conflict (409), payload_too_large (413), rate_limited (429), service_busy (503; retry only with the same Idempotency-Key), internal_error (500).

## Policies and support

- Terms: https://seedancetovideo.com/terms-of-service
- Acceptable Use Policy: https://seedancetovideo.com/acceptable-use-policy
- Refund Policy: https://seedancetovideo.com/refund-policy
- Privacy Policy: https://seedancetovideo.com/privacy-policy
- Contact: https://seedancetovideo.com/contact