Seedance 2.0 Reference API: Programmatic Multi-Modal Video

Programmatic access to multi-modal AI video changes what's possible. One-off clips are great for marketing and content creation, but automated workflows — catalog video generation, per-user personalization, batch content ops — require API access.

The Seedance 2.0 Reference API exposes the full multi-modal capability: up to 9 images, 3 videos, and 3 audio clips per request, programmatically, at the same per-second pricing as the web interface.

When to Reach for the API

Web UI is great for manual, one-at-a-time creative work. The API is for everything else.

API fits when you need:

• Batch generation across hundreds of assets
• Integration with existing content or product pipelines
• Per-user personalized video in an application
• Automated A/B testing of ad creative variants
• Scheduled content generation for daily publishing
• Cataloging workflows tied to database records

Stick with the web UI when:

• You're iterating creatively and need to see/tweak each output
• Volume is low (fewer than 10-20 clips per session)
• You're exploring the tool for the first time

The Endpoint

The Reference-to-video endpoint is:

bytedance/seedance-2.0/reference-to-video

This is the only endpoint you need for multi-modal Reference mode generations. A single request handles text, up to 9 images, up to 3 videos, and up to 3 audio clips. The model fuses all inputs and returns a generated video.

For text-to-video or single-image workflows, use the standard Seedance 2.0 API endpoints instead.

Request Structure

A typical Reference-to-video request includes:

• prompt: Text description of subject and action (required)
• reference_images: Array of up to 9 image URLs or file references
• reference_videos: Array of up to 3 video URLs (optional)
• reference_audio: Array of up to 3 audio URLs (optional)
• duration: Output duration in seconds, 4-15 (required)
• aspect_ratio: One of 16:9, 9:16, 1:1 (required)

Input files can be provided as URLs (publicly accessible) or uploaded directly depending on your integration pattern.

Pricing Through the API

API pricing matches web UI pricing exactly:

| Duration | Credits | USD | |---|---|---| | 4 sec | 243 | $2.42 | | 8 sec | 484 | $4.84 | | 15 sec | 907 | $9.07 |

There is no API access fee and no additional charge for reference uploads. You pay only for generated output seconds.

Credits work the same way across API and web UI. Top up via the pricing page and the same credit pool is used by both interfaces. For high-volume API use, the Max $100 tier (12,000 credits) is the most economical starting point.

Start building with the API. Get API access with 50 free credits on signup. Start free.

Example Use Cases

Catalog Video Automation

For ecommerce platforms with hundreds or thousands of SKUs, the API lets you generate a short product video for every product based on existing product imagery.

Workflow:

1. Query your product database
2. For each product, fetch 5-7 product images
3. Combine with a brand-wide reference bundle (2-3 images)
4. Call the API with prompt template for product reveal
5. Store the returned video URL in your product record
6. Serve on product detail pages

Economics: 500-SKU catalog at 5-second videos = 500 × 303 credits = 151,500 credits = ~$1,515. For a catalog-wide video rollout, that's remarkable value.

Personalized Video Generation

For apps that deliver per-user personalized video — greeting cards, celebration content, onboarding intros — the API lets you generate on-demand videos with user-specific references.

Workflow:

1. User uploads 3-5 personal photos (with consent)
2. Your app combines them with a style reference bundle
3. API call generates a personalized video clip
4. Deliver to the user through your app

This scales to tens of thousands of users without content team overhead.

Ad Creative Variant Generation

Marketing teams running paid social need constant creative variants. The API lets you generate A/B test variants programmatically.

Workflow:

1. Define a brand reference bundle (6-8 images)
2. Write prompt templates for different ad angles
3. Loop through variants, calling the API for each
4. Deliver generated clips to your ad platform
5. Track performance and generate winners at scale

You can produce 50 ad variants in an automated run for ~$150 in API costs, versus traditional production at thousands per variant.

Response Handling

API responses typically include:

• Generation ID: Track the request status
• Status: pending, processing, complete, failed
• Output URL: Available once status is complete
• Metadata: Duration, resolution, file size

Reference mode generations take 60-180 seconds, so your integration should handle async responses. Poll the status endpoint or use webhooks (if available in your account) to get notified on completion.

Do not block user-facing flows on generation completion. Queue the request, notify the user when ready, and deliver asynchronously.

Rate Limits and Concurrency

For most account tiers, concurrent generation limits apply. Plan your batch workflows to respect the limits — queue requests and process them at the allowed concurrency.

For high-volume production workflows, contact platform support about enterprise concurrency limits. Most standard accounts can handle moderate batch work (10-30 concurrent generations) without issue.

Authentication and Keys

API access uses standard key-based authentication. Generate your API key in your account settings after signing up. Keep keys server-side only — never expose them in client code.

Idempotency and Retries

API generations are not natively idempotent because each call costs credits. If a generation fails mid-process, retry logic should check the failed generation's status before re-requesting. A failed generation typically doesn't consume credits, but always verify in your account dashboard.

For production workflows, implement:

• Retry logic with exponential backoff on transient failures
• Status polling or webhook handling for async completion
• Error logging to catch systematic issues
• Credit balance monitoring to alert before you run out

Best Practices for Programmatic Workflows

1. Use consistent reference bundles. For catalog or series work, hash your reference bundles so identical bundles across requests produce more consistent style.

2. Keep prompt templates simple. Programmatic prompts should be generated from structured data, not hand-written per call. Template + data fields is the right pattern.

3. Cache reference file URLs. If you're using URL-based references, ensure the URLs are stable and accessible. Expired S3 URLs or moved files will fail generations.

4. Handle content safety appropriately. The platform has content safety filters. Build graceful handling for filter-rejected requests into your workflow.

5. Log generation metadata. Track every generation — prompt, reference set, duration, credits consumed, output URL — in your application database. This makes debugging and reporting much easier.

Example Batch Workflow

Pseudocode for a batch product video generation workflow:

for product in product_catalog:
    references = build_reference_bundle(
        brand_images,
        product.photo_urls[:4]
    )
    prompt = f"{product.name} product rotates slowly on a clean surface, soft studio lighting, 5 seconds"

    response = seedance_api.generate(
        endpoint="bytedance/seedance-2.0/reference-to-video",
        prompt=prompt,
        reference_images=references,
        duration=5,
        aspect_ratio="16:9"
    )

    generation_id = response.id
    queue_poll_task(generation_id, product.id)

A follow-up poller handles completion and stores the output URL against the product record.

Monitoring and Cost Control

For production API use, set up cost monitoring:

• Daily budget alerts: Alert when daily API spend exceeds a threshold
• Per-workflow caps: Limit batch jobs to a maximum credit spend to prevent runaway automation
• Usage dashboards: Track which workflows consume the most credits
• Credit balance alerts: Top up before running out

These guardrails prevent surprises when you scale automation.

API vs Web UI Pricing Parity

A common question: is there a discount for API use? No — API and web UI both charge the same $0.3024 per second. The API is priced for the work it does, not the interface you use.

Where high-volume users save is in their tier selection. Heavy API users should run on the Max $100 tier for the best per-dollar value.

Getting Started With the API

1. Sign up at seedance.it.com (50 free credits)
2. Generate your API key in account settings
3. Top up a credit pack matching your expected volume
4. Integrate the endpoint in your application
5. Start with small test batches to validate your workflow
6. Scale to production once tested

First API call can be live within an hour of signup for most integrations.

Next Reads

For the full Reference feature set, read the Seedance 2.0 Reference complete guide. For the web UI workflow, see the style-consistent tutorial. For standard Seedance 2.0 API details, check the Seedance 2.0 API guide.

Programmatic multi-modal video is here. Build something new with it.