ByteDance · Reference to Video

Seedance 2.0 Reference To Video

Seedance 2.0 Reference To Video is available in the Business API catalog.

image → video

bytedance/seedance-2.0/reference-to-video

Capabilities

Best for

•Cinematic text-to-video shots
•Short social and ad clips
•Consistent multi-shot sequences
•Look-dev and style exploration

Not for

•Frame-exact rotoscoping
•Feature-length renders
•Pixel-perfect compositing
•Precise on-screen text

Authentication

api key header

The Pika API uses API keys to authenticate requests. Send your key in the X-API-Keyheader. Your API key is a secret. Don't expose it in browsers or other client-side code. Instead, call the API from your server. The signed-in playground uses a portal session and never sends your API key.

header

X-API-Key: YOUR_API_KEY

Endpoint

asynchronous · poll for the result

POSThttps://api.dev.pika.art/v1/media/bytedance/seedance-2.0/reference-to-videogenerate endpoint

GEThttps://api.dev.pika.art/v1/media/jobs/{request_id}poll until completed

GEThttps://api.dev.pika.art/v1/media/jobs/{request_id}/contentget the result URL

Reference Uploads

media inputs

Media inputs accept any public URL. To use a local file, POST its content_type and size_bytes to /v1/media/uploads, PUT the file to the returned upload_url, then pass the url.

upload

# 1. Request a presigned upload URL. Send the file's content
#    type and its exact size in bytes.
curl -X POST https://api.dev.pika.art/v1/media/uploads \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content_type": "image/png", "size_bytes": 12345}'

# The response returns two URLs:
#   upload_url: a temporary URL to upload the file to. Expires in 5 minutes.
#   url:        the permanent Pika URL. Pass it to the model as the input.
# {
#   "upload_url": "https://upload.r2.pika.art/...?X-Amz-Signature=...",
#   "url": "https://cdn.pika.art/v2/media/uploads/org_abc/9f8e7d.png"
# }

# 2. Upload the file to upload_url, then pass url to the model.
curl -X PUT "<upload_url>" \
  -H "Content-Type: image/png" \
  --data-binary @input.png

Generate

POST /v1/media/bytedance/seedance-2.0/reference-to-video

Request

curl -X POST https://api.dev.pika.art/v1/media/bytedance/seedance-2.0/reference-to-video \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "A multi-shot hip-hop music-video sequence with THREE distinct camera shots and\nHARD CUTS between them. A fluffy alpaca at night beside a burgundy vintage BMW\nunder street lights, flash-lit album-cover vibe. Throughout, the alpaca DANCES\nand SHAKES its body rhythmically to the beat — bobbing its head, bouncing on its\nlegs, shimmying so its fluffy fur bounces and sways to the music.\nSHOT 1 — FRONT WIDE: the alpaca stands on the car hood bobbing its head and\nshaking its body to the beat, slow camera push-in.\n[HARD CUT]\nSHOT 2 — SIDE 3/4 PROFILE: the alpaca on the hood nods and sways in profile to\nthe rhythm, slow lateral dolly.\n[HARD CUT]\nSHOT 3 — BACK VIEW, CLOSE, ON THE GROUND: from behind, the alpaca stands on the\npavement close to camera shaking its fluffy hindquarters and tail to the beat,\nglancing back over its shoulder, the BMW behind.\nConfident swagger, dancing to the music, night flash photography, three clearly\ndifferent framings, cinematic, film grain.",
  "ratio": "9:16",
  "generate_audio": true,
  "watermark": false,
  "resolution": "1080p",
  "image_urls": [
    "https://msaocnoosm1a4.pika.art/v2/media/uploads/ff78f2c4-2c28-4245-8264-697530fb255f/91b8c31b5f3a4a26b186d8d63c3ccc63.png",
    "https://msaocnoosm1a4.pika.art/v2/media/uploads/ff78f2c4-2c28-4245-8264-697530fb255f/8c96d6eadb1a48dca1a44d0676ca312e.png",
    "https://msaocnoosm1a4.pika.art/v2/media/uploads/ff78f2c4-2c28-4245-8264-697530fb255f/180a42790ac34fe98979768d54ede35d.png"
  ],
  "video_urls": [
    "https://example.com/reference.mp4"
  ]
}'

Response

{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "queued"
}

Request body

promptstringrequired

Text prompt describing the video to generate.

durationobjectrequired

Duration

ratioenum

Output aspect ratio.

generate_audioboolean

Whether to generate audio for the video.

watermarkbooleandefault: false

Whether to add a watermark to the output video.

image_urlsstring[]

Up to 9 reference images (referenced in the prompt as @Image1…).

video_urlsstring[]

Up to 3 reference videos (referenced in the prompt as @Video1…).

audio_urlsstring[]

Up to 3 reference audio clips (referenced in the prompt as @Audio1…).

resolutionenumrequired

Output resolution.

Accepted values

ratio
resolution

Input modes

Image urlsimage_urls

Use a public URL directly, or POST { content_type, size_bytes } to /v1/media/uploads, PUT the image to the returned upload_url, then pass the url.

Video urlsvideo_urls

Use a public URL directly, or POST { content_type, size_bytes } to /v1/media/uploads, PUT the video to the returned upload_url, then pass the url.

Audio urlsaudio_urls

Use a public URL directly, or POST { content_type, size_bytes } to /v1/media/uploads, PUT the audio to the returned upload_url, then pass the url.

Returns

Returns a job object with status , not the final output. Store the id from the response and poll the job until it completes.

Poll status

GET /v1/media/jobs/{request_id}

Request

curl https://api.dev.pika.art/v1/media/jobs/{request_id} \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "running"
}

Poll the job by id until it reaches a terminal state: completed or failed.

The job object

idstring

Unique identifier for the job.

statusenum

The status of the job.One of:

object

The generation output. Present once the job completes.

errorstring

If the job failed, the reason for the failure.

Get result

GET /v1/media/jobs/{request_id}/content

Request

curl https://api.dev.pika.art/v1/media/jobs/{request_id}/content \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "url": "https://api.dev.pika.art/v1/files/video_8f3a2c91.mp4"
}

Once the job completes, fetch a download URL for the generated media.

Returns

urlstring

Download URL for the generated file.

Errors

shared across calls

Errors use conventional HTTP status codes with a JSON body of the shape {"message": "..."}. The one exception is validation: a request body that fails validation returns 422 with a plain-text body.

Status	When	Body
401 Unauthorized	The API key is missing or invalid.	{"message":"Invalid API key"}
403 Forbidden	The key is not active, or the org balance cannot cover the request.	{"message":"Insufficient org balance"}
404 Not Found	No job with that id exists in your org.	{"message":"media job not found"}
409 Conflict	The result was requested before the job completed, or an Idempotency-Key header was reused with a different body.	{"message":"media job is not ready"}
422 Unprocessable Entity	The request body failed validation: an invalid enum value, a missing required field, a wrong type, or malformed JSON. Returned as plain text, not JSON. A schema-valid parameter combination that cannot be priced returns the same status with a JSON message.	Unprocessable entity
429 Too Many Requests	Org limit reached: requests per minute or day, or concurrent jobs. Check the Retry-After header.	{"message":"rate limit exceeded: rpm"}
503 Service Unavailable	The model rail or a backend dependency is temporarily unavailable. Retry with backoff.	{"message":"media dispatch unavailable"}

Pricing

only successful runs are charged

Tier	Price
720p · no video input	$0.30 / second
720p · with video input	$0.18 / second

Per-model pricing

Transparent, usage-based rates for every ByteDance model.

Model	Type
Seedream 4.0 Image Editing	Image to Image	$0.03 / image
Seedream 4.0	Text to Image	$0.03 / image
Seedream 5.0 Lite Image Editing	Image to Image	$0.035 / image
Seedream 5.0 Lite	Text to Image	$0.035 / image
Seedream 4.5	Text to Image	$0.04 / image
Seedream 5.0 Pro Text to Image	Text to Image	from $0.045 / image
Seed Audio 1.0	Text to Audio	$0.15 / min
Seedance 2.0 Mini	Reference to Video	from $2.205
Seedance 2.0Current	Reference to Video	from $2.52
Seedance 2.0 Fast	Reference to Video	from $3.465
Seedance 2.0 Mini	Image to Video	$3.675
Seedance 2.0 Mini	Text to Video	$3.675
Seedance 2.0	Image to Video	from $4.2
Seedance 2.0	Text to Video	from $4.2
Seedance 2.0 Fast	Image to Video	$5.88
Seedance 2.0 Fast	Text to Video	$5.88
Seedream 5.0 Pro Image Editing	Image to Image	Custom

Seedream 4.0 Image Editing

$0.03 / image

Image to Image

Seedream 4.0

$0.03 / image

Text to Image

Seedream 5.0 Lite Image Editing

$0.035 / image

Image to Image

Seedream 5.0 Lite

$0.035 / image

Text to Image

Seedream 4.5

$0.04 / image

Text to Image

Seedream 5.0 Pro Text to Image

from $0.045 / image

Text to Image

Seed Audio 1.0

$0.15 / min

Text to Audio

Seedance 2.0 Mini

from $2.205

Reference to Video

Seedance 2.0

Current

from $2.52

Reference to Video

Seedance 2.0 Fast

from $3.465

Reference to Video

Seedance 2.0 Mini

$3.675

Image to Video

Seedance 2.0 Mini

$3.675

Text to Video

Seedance 2.0

from $4.2

Image to Video

Seedance 2.0

from $4.2

Text to Video

Seedance 2.0 Fast

$5.88

Image to Video

Seedance 2.0 Fast

$5.88

Text to Video

Seedream 5.0 Pro Image Editing

Custom

Image to Image