# Seedance 2.5 API Agent Guide

Updated: 2026-07-09
Site: https://seedance25api.io
Status: Provider-mediated access (Expected)

Use this file when you are an AI coding agent helping a human integrate Seedance 2.5 API.

## Primary Context URLs

- Full context: https://seedance25api.io/llms-full.txt
- OpenAPI schema: https://seedance25api.io/openapi.json
- Human agent page: https://seedance25api.io/agent
- Quickstart: https://seedance25api.io/api
- Pricing and billing model: https://seedance25api.io/pricing

## Hard Rules

- Do not invent or hardcode an API key.
- Ask the human to create EVOLINK_API_KEY before live calls.
- Build behind a configurable model parameter.
- Surface cost as an estimate — public rates are not published yet.
- Validate duration, quality, and reference counts before sending.
- Use polling or callback_url for async completion.
- If the model is unavailable for the account, keep the request shape and switch models via the configurable parameter once access is enabled.

## Recommended Integration Flow

1. Read https://seedance25api.io/llms-full.txt.
2. Load https://seedance25api.io/openapi.json for request shape.
3. Add an environment variable named EVOLINK_API_KEY.
4. Build the integration behind a configurable model parameter.
5. Validate prompt, duration, quality, and reference counts locally.
6. Surface cost as an estimate — public rates are not published yet.
7. Ask the human to create a provider key before live calls.
8. Submit a short low-cost test (POST https://api.evolink.ai/v1/videos/generations) after the key exists.
9. Poll GET https://api.evolink.ai/v1/task-detail?id=<id> or use callback_url until completion.
10. Handle pending / processing / completed / failed job states, plus HTTP 429 (rate limited) and 503 (model unavailable) responses.

## Human Key Handoff

Tell the human:

```text
I can wire the Seedance 2.5 API integration now, but I need a provider API key before live calls.
Create a key here: https://evolink.ai/dashboard/keys?utm_source=seedance25api.io&utm_medium=referral&utm_campaign=agent&utm_content=agent-md-key
Then add it as EVOLINK_API_KEY in the project environment.
```

## Model IDs To Track

- Reference-to-video model ID: seedance-2.5-reference-to-video (Expected) - Confirmed in EvoLink API docs; model is pre-release ("not yet available"). References are optional, so a prompt-only call behaves as text-to-video.
- Text-to-video / image-to-video IDs: Pending provider docs (Pending) - Not yet confirmed. Keep the model parameter configurable so the same code can switch when the IDs are published.

## Limits To Validate

- Duration: 4-30 seconds (Expected) - Use 5s or 8s for first integration tests to reduce cost.
- Launch resolutions: 480p and 720p (Expected) - Treat 1080p and 4K as pending until public provider docs confirm them.
- Image references: up to 30 (Expected) - Cap may change at launch; validate before sending production jobs.
- Video references: up to 10, total reference video duration <= 30s (Expected) - Prefer short, clear references for first tests.
- Audio references: up to 10, total reference audio duration <= 30s (Expected) - Do not rely on audio-only R2V unless provider docs explicitly allow it.

## Minimal Request

```json
{
  "model": "seedance-2.5-reference-to-video",
  "prompt": "A clean product shot, slow dolly in, soft daylight, stable subject identity.",
  "duration": 5,
  "quality": "720p",
  "generate_audio": true
}
```

Model is pre-release — keep it configurable. References (image_urls / video_urls / audio_urls) are optional; a prompt-only call behaves as text-to-video.