AI Video API Documentation

Everything you need to integrate AI video generation into your application: authentication, text-to-video and image-to-video requests, predictable pricing, rate limits, and real-time job status for a Seedance-powered REST API workflow.

Authentication

All API requests require a Bearer token. Use your API key in the Authorization header:

Authorization: Bearer sd_your_api_key_here

API keys start with sd_ and can be created from your dashboard or via the API keys endpoint. Keep your keys secret.

Base URL

https://usvideoapi.com/v1

Quickstart

1. Create an account and add funds

Register an account and add prepaid balance to get started.

2. Submit a generation request

curl -X POST https://usvideoapi.com/v1/videos \
  -H "Authorization: Bearer sd_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A drone shot over a misty mountain lake at sunrise",
    "resolution": "1080p",
    "duration": 5,
    "aspect_ratio": "16:9",
    "negative_prompt": "speech, captions, logos, low realism"
  }'

3. Poll for completion

curl https://usvideoapi.com/v1/videos/JOB_ID \
  -H "Authorization: Bearer sd_your_key"

# Response when complete:
{
  "id": "job_abc123",
  "status": "completed",
  "video_url": "https://...",
  "duration": 5,
  "cost_cents": 120
}

Create Video

{
  "id": "job_abc123",
  "status": "pending",
  "resolution": "1080p",
  "duration": 5,
  "price": "$2.00",
  "estimated_time": "30-120 seconds"
}

Get Video Status

# 1. Submit job once
# 2. Save job.id
# 3. Poll every ~5 seconds
# 4. Stop when status is completed or failed

while status not in ["completed", "failed"]:
    sleep(5)
    status = GET /v1/videos/{id}

if status == "completed":
    download(video_url)
else:
    log(detail)
    retry_with_adjusted_prompt()

List Videos

Delete Video

Account Info

{
  "email": "[email protected]",
  "balance_cents": 4850,
  "total_jobs": 127,
  "total_spent_cents": 15200
}

API Keys

Pricing

{
  "480p":  { "per_second": 0.10 },
  "720p":  { "per_second": 0.25 },
  "1080p": { "per_second": 0.50 }
}

Error Handling

Standard error response shape

All API errors return a JSON body with a detail string. Use the status code for control flow and display detail directly to operators or rewrite it for end users.

{
  "detail": "Insufficient balance. Need $2.00, have $0.75. Top up at /v1/account/topup"
}

{
  "detail": "Image payload too large. Resize or compress the source image before retrying."
}

{
  "detail": "Video generation capacity is temporarily full. Retry in a few minutes or lower your request volume."
}

{
  "detail": "Generation was blocked by model safety checks. Remove dialogue, speech, celebrity or real-person references, brand/IP references, and other sensitive audio cues, then retry with a silent visual-only prompt."
}

{
  "detail": "Video generation service timed out. Please try again."
}

Retry guidance by failure type

Safety & Moderation

US Video API sits on top of a commercial foundation model with its own safety review. That means some generations can be blocked even when the prompt appears harmless. This is expected behavior for a production API and should be handled as part of your workflow.

Recommended production pattern

• Default to silent visual-only prompts for product, workflow, and landing-page content.
• Use negative_prompt to exclude speech, captions, logos, and unwanted objects.
• Retry with a shorter, more literal prompt if a request is blocked.
• Build a fallback prompt library instead of assuming every creative prompt will pass on the first try.

For a practical checklist and prompt rewrite patterns, use the Prompt Safety Guide.

Rate Limits

Models

Powered by Seedance 2.0. Public self-serve documentation currently covers text-to-video and image-to-video workflows. Published request controls include 480p, 720p, and 1080p resolutions, durations from 4-15 seconds, and aspect ratios for 16:9, 9:16, 1:1, and 4:3.

Deployment Checklist

Before you ship a real workflow on top of the API, make sure your application handles the operational basics below.

• Store the returned job ID from POST /v1/videos immediately.
• Poll every few seconds instead of hammering the status endpoint.
• Handle failed jobs as a normal production state, not an exception you ignore.
• Compress image-to-video inputs before base64 encoding them.
• Surface the detail field to operators for 402, 413, 429, 502, and 504 responses.
• Queue locally or throttle bursts before you hit published limits.
• Route high-volume or launch-critical workloads through the enterprise evaluation path early.

Documentation FAQ

How do I authenticate with the AI video API?

Use a Bearer API key in the Authorization header. Keys are created from your dashboard and should be stored server-side.

How do I generate video through the REST API?

Submit a job to /v1/videos, then poll the status endpoint until the job completes. This page documents the request and response shape for that flow.

Where do I manage billing, API keys, and shared access?

The API endpoints are documented here. Account management, billing workflow, and shared-access guidance live in the management guide and enterprise guide.

Why was my generation blocked even though the prompt looked normal?

Some requests are rejected by model safety review, especially prompts that imply dialogue, sensitive audio, copyrighted characters, celebrity likenesses, or unclear brand/IP usage. Keep prompts literal and visual-first, then use the Prompt Safety Guide to rewrite and retry.