# Seedance 2.0 Mini (`seedance-2.0-mini`)

> ByteDance Seedance 2.0 Mini, the economical tuning for drafts and volume: text or a first frame or reference images to video, with native audio. On Pershot, every job is quoted before it runs, credits are held and settled on delivery, and failed or refused jobs are not charged.

Generated from the same catalog, OpenAPI document and price engine the API uses. Live status (available, degraded, paused) and suppliers: GET /v1/models or the MCP tool list_models.
The same facts as JSON: the MCP tool `get_model` with model "seedance-2.0-mini". All models: https://pershot.app/llms.txt

## What it is
- Model id: `seedance-2.0-mini` (video, Seedance 2.0; tag: economy)
- Supplier model version: dreamina-seedance-2-0-mini-260615
- Endpoint: POST https://api.pershot.app/v1/videos/generations

## Inputs
- text: `prompt` (required). 2 to 2,000 characters; describe the subject, the camera and the light.
- first frame: `image_url`. One image the clip starts from: a public https URL or a link from POST /v1/uploads.
- reference images: `reference_image_urls`. Up to 9 images for subject and style; refer to them in the prompt as @image1, @image2. Not with a first frame.

## Legal values and defaults
- duration: 4 to 15 whole seconds (default 5)
- resolution: 480p, 720p (default 720p)
- aspect_ratio: 16:9, 9:16, 1:1 (default 16:9)
- generate_audio: true or false (default true); the price is the same
- first frame or reference images: one or the other, not both
- output: MP4, 24 fps; 480p: 16:9 864×496, 9:16 496×864, 1:1 640×640; 720p: 16:9 1280×720, 9:16 720×1280, 1:1 960×960

## Request fields
JSON body; unknown fields are refused (400 invalid_request). Header `Idempotency-Key` is required.
- model: string, required, seedance-2.0-fast · seedance-2.0-mini · auto. Send "seedance-2.0-mini" for this model.
- prompt: string, required, 2–2000 characters. What to render: the subject, the camera and the light.
- duration: integer, optional, default 5, 4–15. Output length in whole seconds.
- resolution: string, optional, default "720p", 480p · 720p. 480p for drafts, 720p for delivery; each is its own render and price.
- aspect_ratio: string, optional, default "16:9", 16:9 · 9:16 · 1:1. Frame shape. A square 480p clip is smaller, so it costs a little less.
- generate_audio: boolean, optional, default true. Native audio. The price is the same on or off.
- image_url: string, optional, public https URL. First frame: a public https URL or a link from POST /v1/uploads. Not with reference images.
- reference_image_urls: string[], optional, up to 9 items, public https URL. Reference images for subject and style; @image1, @image2 in the prompt. Not with a first frame.
- seed: integer, optional, 0–2147483647. Accepted and not used: Seedance 2.0 has no seed.
- quote_id: string, optional, starts with qt_. Run at a quote from POST /v1/quotes (valid 10 minutes). Send exactly one of quote_id or max_credits.
- max_credits: number, optional, > 0. The most this job may cost; above it the job is refused, never charged. Send exactly one of quote_id or max_credits.
- webhook_url: string, optional, public https URL. An https URL that receives this job's events (see Async flow).
- end_user_id: string, optional, 1–128 characters. For approved developer accounts (developer API access is by application): your own user id for this request, shown in usage.
- project_id: string, optional, starts with prj_. Attribute the job to one of your projects; the project's budget applies.
- shot_id: string, optional, starts with sht_. Make the job a new version of this project shot.
- routing_preference: string, optional, stability · speed. How to order the model's suppliers: stability (default) or speed. The price is the same with every supplier.
- enhance: object, optional. Optional HD path: after the render, an AI upscale to 1080p, 2K or 4K (the video-upscale tool), labeled AI Enhanced; the original is kept. Priced as lines of its own and max_credits covers both. Quote it with POST /v1/quotes and the same enhance block.

## Prices
- Per billed second (for budgeting): $0.020 at 480p, $0.042 at 720p. Audio on or off: same price.
- Credits per clip by resolution, aspect ratio and duration (1 credit = $0.01):

| Resolution, ratio | 4 s | 5 s | 6 s | 7 s | 8 s | 9 s | 10 s | 11 s | 12 s | 13 s | 14 s | 15 s |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 480p 16:9 | 8 | 10 | 12 | 14 | 16 | 18 | 20 | 22 | 24 | 26 | 28 | 30 |
| 480p 9:16 | 8 | 10 | 12 | 14 | 16 | 18 | 20 | 22 | 24 | 26 | 28 | 30 |
| 480p 1:1 | 8 | 10 | 12 | 13 | 15 | 17 | 19 | 21 | 23 | 25 | 26 | 28 |
| 720p 16:9 | 17 | 21 | 25 | 30 | 34 | 38 | 42 | 46 | 50 | 55 | 59 | 63 |
| 720p 9:16 | 17 | 21 | 25 | 30 | 34 | 38 | 42 | 46 | 50 | 55 | 59 | 63 |
| 720p 1:1 | 17 | 21 | 25 | 30 | 34 | 38 | 42 | 46 | 50 | 55 | 59 | 63 |

- The creative and developer API price lists are the same today. POST /v1/quotes (MCP quote) returns the exact price of a job before it runs, and a job never costs more than its quote or max_credits.

## Example request
Body:
```json
{
  "model": "seedance-2.0-mini",
  "prompt": "Creator holds the bottle to camera and explains one benefit, handheld, natural room light.",
  "duration": 10,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "generate_audio": true,
  "max_credits": 42
}
```

cURL:
```sh
curl https://api.pershot.app/v1/videos/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini",
    "prompt": "Creator holds the bottle to camera and explains one benefit, handheld, natural room light.",
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "max_credits": 42
  }'
```

Python:
```python
import os, uuid, requests

res = requests.post(
    "https://api.pershot.app/v1/videos/generations",
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "seedance-2.0-mini",
        "prompt": "Creator holds the bottle to camera and explains one benefit, handheld, natural room light.",
        "duration": 10,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "generate_audio": True,
        "max_credits": 42
    },
)
job = res.json()  # 202 → {"id": "job_…", "status": "queued"}
```

JavaScript (Node):
```js
const res = await fetch("https://api.pershot.app/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.0-mini",
    prompt: "Creator holds the bottle to camera and explains one benefit, handheld, natural room light.",
    duration: 10,
    resolution: "720p",
    aspect_ratio: "16:9",
    generate_audio: true,
    max_credits: 42
  }),
});
const job = await res.json(); // 202 → { id: "job_…", status: "queued" }
```

## Async flow
1. Create: POST https://api.pershot.app/v1/videos/generations with the Authorization and Idempotency-Key headers. Answers 202 with a Job (id "job_…", status "queued", money_status "reserved"): the credits are held, not charged.
2. Poll: GET https://api.pershot.app/v1/jobs/{id} until status is succeeded, failed or cancelled. "unknown" means the outcome is being checked with the model: keep polling; the credits stay held and are never charged twice. Statuses: queued, processing, succeeded, failed, cancelled, unknown.
3. Or webhooks: pass `webhook_url` (https) for job.queued, job.processing, job.succeeded, job.failed, job.cancelled. X-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>, keyed with your whsec_ secret; refuse timestamps older than five minutes and dedupe on X-Event-Id. A 2xx within 10 seconds counts as delivered; failed deliveries retry after 1 min, 5 min, 30 min, 2 h and 6 h. Redirects are not followed.
4. Results: outputs[].url is a signed link valid 24 hours; GET the job again for a fresh one. Files are kept 12 months (outputs_expire_at), longer when saved to the library or a project.
- Idempotency: The same Idempotency-Key within 24 hours returns the same job with HTTP 200, so a retry after a timeout never creates or charges a second job. Use a new key for a new job.
- Cancel: POST https://api.pershot.app/v1/jobs/{id}/cancel refunds the held credits unless the model has already accepted the job.
- Charge: Succeeded: charged the quoted credits at most (credits_charged). Failed, refused or canceled before the model started: the held credits are refunded and nothing is charged.

## Errors
Shape: {"error": {"code", "message", "param", "details", "request_id"}}. Retry: fix = change the request first; wait = the same request may work later; no = do not send it again as is.
- 400 invalid_request (retry: fix): A field is missing or out of range; `param` names it. Fix it and send again. Nothing was quoted or held.
- 401 unauthorized (retry: fix): Check the key and the `Authorization: Bearer` header.
- 402 insufficient_credits (retry: fix): Not enough credits in the account this credential spends (`details.account`: creative or api). Top up, then retry with the same Idempotency-Key.
- 403 forbidden_model (retry: fix): The key's allowlist leaves this model out, or the model is paused. Add it to the key in the studio or use another key.
- 403 region_not_supported (retry: no): This model is not sold in the caller's region. GET /v1/models lists what is.
- 403 developer_api_closed (retry: no): Developer API access is by application: request it on the API keys page in the studio. For the person's own work, sign in instead (MCP or device login): no key is needed.
- 403 member_connections_paused (retry: no): Connecting a person's own AI agent is paused for now. Nothing was charged; the studio still works.
- 404 not_found (retry: fix): The quote or job id is unknown to this account. Quotes belong to the account that made them.
- 409 quote_expired (retry: fix): Quotes last 10 minutes. Get a new quote, or send max_credits instead.
- 409 price_changed (retry: fix): The price is above your max_credits cap. Quote again or raise the cap; nothing was charged.
- 422 content_rejected (retry: fix): The prompt or an image was refused. Nothing was charged. Change the prompt or the images.
- 429 rate_limited (retry: wait): Too many requests. Wait for Retry-After, then send the same request again.
- 429 concurrency_limited (retry: wait): Too many jobs running at once for this account. Wait for one to finish (Retry-After), then retry.
- 500 internal_error (retry: wait): Our error. Retry with the same Idempotency-Key: a job that was created is returned, never created twice.
- 503 upstream_unavailable (retry: wait): The model is not responding. Retry later; a job that never starts is not charged.

## Limits
- enforced: we check it and answer 400 invalid_request (or refuse the upload) before anything is quoted or held. upstream: the supplier refuses past it; the job fails with invalid_request and nothing is charged. recommended: not checked. Links to other hosts are never fetched by us, so the supplier checks those images.
Limits (seedance-2.0-mini):
  - prompt_length: 2 to 2,000 characters [enforced; past it: 400 invalid_request before any quote or hold (param prompt)]
  - prompt_words_en: up to 1,000 English words [recommended; past it: accepted; a longer prompt may be followed less closely]
  - prompt_chars_zh: up to 500 Chinese characters [recommended; past it: accepted; a longer prompt may be followed less closely]
  - duration: 4 to 15 seconds (default 5) [enforced; past it: 400 invalid_request before any quote or hold (param duration)]
  - resolution: 480p, 720p (default 720p) [enforced; past it: 400 invalid_request before any quote or hold (param resolution)]
  - aspect_ratio: 16:9, 9:16, 1:1 (default 16:9) [enforced; past it: 400 invalid_request before any quote or hold (param aspect_ratio)]
  - seed: ignored [upstream; past it: accepted and not used]
  - input_video_seconds: 2 to 15 seconds [enforced; past it: 400 invalid_request before any quote or hold (param input_video_seconds)]
  - reference_images: up to 9 images [enforced; past it: 400 invalid_request before any quote or hold (param reference_image_urls)]
  - first_frame_or_references: image_url or reference_image_urls, not both [enforced; past it: 400 invalid_request before any quote or hold (param reference_image_urls)]
  - image_side: 300 to 6,000 px per side [enforced, uploads only; past it: uploads: 400 invalid_request before any quote or hold; links to other hosts: the supplier refuses the job, nothing is charged]
  - image_aspect: 0.4 to 2.5 width ÷ height [enforced, uploads only; past it: uploads: 400 invalid_request before any quote or hold; links to other hosts: the supplier refuses the job, nothing is charged]
  - upload_image_bytes: up to 10 MB [enforced; past it: POST /v1/uploads answers 400 invalid_request]
  - upload_image_formats: JPEG, PNG, WebP [enforced; past it: POST /v1/uploads answers 400 invalid_request]
  - external_image_bytes: up to 30 MB [upstream; past it: the supplier refuses the job; it fails and nothing is charged]
  - external_image_formats: JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF [upstream; past it: the supplier refuses the job; it fails and nothing is charged]
  - output_pixels: 480p: 16:9 864×496, 9:16 496×864, 1:1 640×640; 720p: 16:9 1280×720, 9:16 720×1280, 1:1 960×960 px [upstream; past it: fixed: every output has it]
  - frame_rate: 24 fps [upstream; past it: fixed: every output has it]
  - output_format: MP4 [upstream; past it: fixed: every output has it]
  - upload_link_ttl: 7 days [enforced; past it: the link answers 403 after that]
  - output_link_ttl: 24 hours [enforced; past it: the link answers 403 after that]

## MCP
- Server: https://mcp.pershot.app/mcp. Sign in through the client (OAuth), or send a connection code as a Bearer header. A developer API key (by application) also works as a Bearer header.
- `get_model`: These facts as JSON (free, read only).
- `list_models`: Every model with its live status and suppliers, as GET /v1/models.
- `quote`: The exact price of one job and a quote_id valid 10 minutes, as POST /v1/quotes.
- `create_upload`: Check a public https image link so it can be used as image_url.
- `generate_video` (spends credits): Run the job, as POST /v1/videos/generations; needs idempotency_key and quote_id or max_credits.
- `wait_for_job`: Wait up to 60 seconds for the job, then return it.
- `get_job`: The job's status, output links and charge, as GET /v1/jobs/{id}.
- `cancel_job`: Cancel a job the model has not started; its credits are refunded.

## Links
- page: https://pershot.app/models/seedance-2-0-mini
- api reference: https://pershot.app/models/seedance-2-0-mini/api
- llms txt: https://pershot.app/models/seedance-2.0-mini/llms.txt
- all models: https://pershot.app/llms.txt
- openapi: https://pershot.app/api/v1/openapi.json
- docs: https://pershot.app/docs
- migrate: https://pershot.app/docs/migrate
- pricing method: https://pershot.app/pricing/method