Video Generation API
Developer Deep Dive

API Overview

US Video API is a standard REST API that accepts JSON request bodies and returns JSON responses. All endpoints are served over HTTPS at https://usvideoapi.com. The API uses bearer token authentication and returns standard HTTP status codes.

Video generation is asynchronous. You submit a job, receive a job ID, and then poll for completion or receive a webhook callback. This design handles the 30–90 second generation time without blocking your HTTP connection.

Authentication

Every request must include your API key in the Authorization header:

Authorization: Bearer usv_live_abc123def456...

API keys are generated when you register and can be rotated at any time from your dashboard. Keys prefixed with usv_live_ are production keys that deduct from your balance. Keys prefixed with usv_test_ are sandbox keys that return mock responses without charge.

• Never expose your API key in client-side code or public repositories
• Use environment variables or a secrets manager to store keys
• Rotate keys immediately if you suspect a leak

Core Endpoints

Webhooks

Instead of polling for job completion, you can provide a webhook_url in your generation request. When the job completes (or fails), we send an HTTP POST to your URL with the full job object:

{
  "event": "video.completed",
  "job_id": "job_8f3a...",
  "status": "completed",
  "video_url": "https://cdn.usvideoapi.com/...",
  "duration_actual": 5.0,
  "resolution": "720p",
  "cost": "$1.25",
  "created_at": "2026-04-21T14:30:00Z",
  "completed_at": "2026-04-21T14:31:12Z"
}

Webhook deliveries include an X-Signature header containing an HMAC-SHA256 signature. Verify this signature using your webhook secret (available in your dashboard) to ensure the payload is authentic and has not been tampered with.

If your webhook endpoint returns a non-2xx status code, we retry delivery up to 3 times with exponential backoff (30s, 120s, 480s).

Error Handling

The API returns standard HTTP status codes with descriptive error messages:

• 400 Bad Request — Invalid parameters (e.g., duration > 10, missing prompt)
• 401 Unauthorized — Missing or invalid API key
• 402 Payment Required — Insufficient balance for the requested generation
• 404 Not Found — Job ID does not exist or belongs to another account
• 429 Too Many Requests — Rate limit exceeded (see below)
• 500 Internal Server Error — Server-side error; retry with backoff
• 503 Service Unavailable — Temporary capacity constraint; retry after the Retry-After header

All error responses include a JSON body with error (machine-readable code) and message (human-readable description). Build your error handling around the HTTP status code, not the message text, as messages may change.

Rate Limits

Default rate limits are designed to prevent abuse while allowing production-scale workloads:

• Concurrent jobs — 10 simultaneous generation jobs per account (default)
• Requests per minute — 60 API requests per minute across all endpoints
• Burst — Up to 20 requests in a 5-second window

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. If you need higher limits, contact us — enterprise accounts can have limits raised to 50+ concurrent jobs.

Batch Generation

For workflows that require generating many videos (e.g., creating product videos for an entire catalog), use the concurrent job limit efficiently:

import asyncio, aiohttp

async def generate_video(session, prompt, resolution="720p"):
    async with session.post(
        "https://usvideoapi.com/v1/videos",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"prompt": prompt, "resolution": resolution,
              "duration": 5, "webhook_url": WEBHOOK_URL}
    ) as resp:
        return await resp.json()

async def batch_generate(prompts, max_concurrent=10):
    sem = asyncio.Semaphore(max_concurrent)
    async with aiohttp.ClientSession() as session:
        async def limited(prompt):
            async with sem:
                return await generate_video(session, prompt)
        return await asyncio.gather(
            *[limited(p) for p in prompts]
        )

# Generate 100 product videos, 10 at a time
prompts = [f"Product showcase: {name}" for name in product_names]
jobs = asyncio.run(batch_generate(prompts))

Using webhooks with batch generation is strongly recommended. Instead of polling hundreds of jobs, let the API notify your server when each video is ready.

SDK & Libraries

While the REST API works with any HTTP client in any language, we provide official client libraries for common languages:

• Python — pip install usvideoapi
• Node.js — npm install @usvideoapi/sdk
• Go — go get github.com/usvideoapi/go-sdk

All SDKs handle authentication, polling, retry logic, and webhook signature verification. They are thin wrappers — you are never locked in. The raw REST API is always available.

Full API reference with request/response schemas is available at usvideoapi.com/docs.