Video Generation API

Generate short AI videos with OpenAI Sora 2, xAI Grok Imagine, or ByteDance Seedance. Text (or image) prompt in, MP4 URL out — paid per call with USDC on Base via x402.

• Endpoint: POST https://blockrun.ai/v1/videos/generations
• Poll: GET https://blockrun.ai/v1/videos/generations/{id}?model=…&duration=…
• Payment: x402, USDC on Base mainnet (network: "base", x402Version: 2). Minimum charge $0.003.

Sample output

A real azure/sora-2 clip generated through this exact API — 4s, 720p, synced audio (text-to-video):

<video src="https://blockrun.ai/api/media/media/videos/2026/05/27/video_6a1670cac7a081909309f1b6b85fbb40-6af6c7a4.mp4" controls muted width="480"></video>

▶️ Open the sample clip directly if the inline player doesn't load.

How it works — async submit → poll → settle

Video generation is asynchronous and two-step. A clip takes ~60–180s upstream, far longer than a single HTTP request should stay open, so the flow is:

Key guarantees:

Available models

Notes:

• Sora 2 accepts only duration_seconds of 4, 8, or 12 — any other value returns 400 listing the allowed set. Text-to-video only (no image_url). Output is 720p with synchronized audio, portrait or landscape.
• Grok Imagine accepts duration_seconds from 1 to 15 (default 8); it accepts an optional image_url and ignores the Seedance-only tuning params (resolution, aspect_ratio, generate_audio, etc.).
• Seedance supports a default of 5s and a per-tier maximum — seedance-2.0 / seedance-2.0-fast allow up to 15s, seedance-1.5-pro up to 12s (the gateway returns 400 for a duration_seconds above the tier max). The gateway bumps the default to 720p and sets generate_audio per the t2v/i2v split below. Only Seedance 2.0 / 2.0-fast accept a real_face_asset_id (ta_xxxx) for character/identity consistency, multiple reference images, and reference video/audio (r2v). seedance-2.0-fast finishes in ~60–80s; seedance-2.0 (Pro) is higher quality and slower.

Image-to-video options

Whether you can seed generation from an image — and how — depends on the subject:

• Non-human subject (product, scene, animal, object): pass image_url (a public URL to the first frame) on azure/sora-2, Grok, or any Seedance model. For azure/sora-2 the gateway resizes the seed image server-side to Sora's exact required dimensions (1280×720 / 720×1280). Seedance image-to-video is billed at the same per-token rate as text-to-video.
• A specific real person: you cannot upload a face to Sora (see the note below). Use Seedance 2.0 / 2.0-fast + a RealFace ta_xxxx asset — enroll the person once with their consent (RealFace, ~1-min on-phone liveness, $0.012), then pass real_face_asset_id. Details in Character consistency below.
• An AI character / mascot: same flow with a Virtual Portrait asset (no KYC, $0.012).

Request parameters (POST body, JSON)

Pricing

All prices include the gateway's standard 5% margin — i.e. these are the amounts quoted in the 402 challenge and actually billed in USDC.

Seedance token math: at the 720p default a clip uses ~21,690 tokens/second (a 5s clip ≈ 108,450 tokens). Price = duration × 21,690 × resolution-factor × rate-per-M ÷ 1,000,000 × 1.05. Image-to-video is billed at the same per-token rate as text-to-video (no i2v discount). The resolution token factor relative to 720p (=1) is: 360p ×0.3, 480p ×0.5, 540p ×0.7, 720p ×1, 1080p/1K ×2.25, and 4K ×9 (area-proportional) — so dropping to 480p halves the per-clip cost and 1080p/4K cost proportionally more. 4K (real 3840×2160) is available only on bytedance/seedance-2.0; on seedance-1.5-pro/seedance-2.0-fast the ceiling is 1080p/1K and 4K returns a 400. 2K is never offered (not produced upstream). Reference video/audio inputs (r2v) add a surcharge: ×(1 + 1.0·#refVideos + 0.3·#refAudios). Per-second models (Grok, Sora) ignore resolution and reference surcharges.

One-time enrollment fees (separate from per-call billing):

Responses

1. POST → 202 Accepted (job submitted)

{
  "id": "azure:vidjob_abc123",
  "object": "video.generation.job",
  "status": "queued",
  "model": "azure/sora-2",
  "duration_seconds": 8,
  "price": { "amount": "0.840000", "currency": "USD" },
  "payment_status": "verified",
  "created": 1776443975,
  "poll_url": "/api/v1/videos/generations/azure%3Avidjob_abc123?model=azure%2Fsora-2&duration=8"
}

The id is a composite "{provider}:{upstreamId}". The poll_url already encodes the required ?model and ?duration query params — preserve them when polling.

2. GET poll → 202 (still generating)

{
  "id": "azure:vidjob_abc123",
  "object": "video.generation.job",
  "status": "in_progress",
  "model": "azure/sora-2",
  "payment_status": "verified",
  "note": "Upstream is still generating. Poll again in 5-10s. No charge until status=completed."
}

status is queued or in_progress. Keep polling every 5–10s.

3. GET poll → 200 (completed — charged here)

{
  "id": "azure:vidjob_abc123",
  "object": "video.generation.job",
  "status": "completed",
  "model": "azure/sora-2",
  "created": 1776444180,
  "data": [
    {
      "url": "https://blockrun.ai/api/media/media/videos/2026/05/27/<id>.mp4",
      "source_url": "https://<upstream-host>/<id>.mp4",
      "duration_seconds": 8,
      "request_id": "vidjob_abc123",
      "backed_up": true
    }
  ],
  "payment": { "status": "settled", "tx_hash": "0x…", "network": "base" }
}

On settlement the response also carries PAYMENT-RESPONSE and X-Payment-Receipt (the on-chain tx hash) headers. A re-poll of an already-settled job returns the same body with payment.status: "already_settled" and no new charge.

GET poll → 200 (failed — not charged)

{
  "id": "azure:vidjob_abc123",
  "object": "video.generation.job",
  "status": "failed",
  "model": "azure/sora-2",
  "error": "<upstream reason>",
  "payment_status": "not_charged",
  "note": "Upstream generation failed. No payment was taken."
}

Response fields

Examples

Image-to-video (Grok / Seedance)

curl -X POST https://blockrun.ai/v1/videos/generations \
  -H "Content-Type: application/json" \
  -H "X-Payment: $PAYMENT_HEADER" \
  -d '{ "model": "bytedance/seedance-2.0", "prompt": "the subject turns and smiles", "image_url": "https://example.com/portrait.jpg" }'

Character consistency (Seedance 2.0 fast / pro)

Pass a ta_xxxx asset from a Virtual Portrait or RealFace enrollment to keep the same identity across clips. Mutually exclusive with image_url.

{
  "model": "bytedance/seedance-2.0",
  "prompt": "the subject smiles warmly and waves at the camera",
  "real_face_asset_id": "ta_abc123xyz"
}

Timing

Set your HTTP client timeout to at least 180s per poll. The POST handler itself caps the upstream submit at ~20s (returns 504, no charge, if upstream doesn't acknowledge).

Error codes

What's next?

Also useful: Music Generation · Error Handling · Real-person video walkthrough.