Video Generations

Minimum-discount routing: Prefix the path with a min{N} segment (e.g. /min30/v1/video/generations) to require marketplace seller offers to meet a minimum estimated buyer discount before routing. Buyer-owned providers are not covered. See Minimum-Discount Routing.

Async video generation via the marketplace. Submit a job, poll for status, retrieve results.

Submit Job

POST/v1/video/generations

Auth: API key required (Authorization: Bearer ***).

Name
model
Type
string
required
Description
Model ID, e.g. venice-runway-gen4-5-text; legacy venice-video-gen maps to a live Venice model
Name
prompt
Type
string
required
Description
Text prompt (max 2000 chars)
Name
duration_seconds
Type
integer
Description
Video duration. Optional; omitted values use the model's cheapest/default duration when known
Name
image_url
Type
string
Description
Image-to-video start frame — an https:// URL or a data: URI. Required by image-to-video-only models (see Image-to-Video below)
Name
end_image_url
Type
string
Description
Transition end frame for models that interpolate between two stills (equivalent to input_images with role: "end")
Name
input_images
Type
array
Description
Source images for image-to-video / transition / reference models. Each entry is an https/data: URI string — positional [start] or [start, end] — or an object { "url": "...", "role": "start" | "end" | "reference" }. Max 8 images per request
Name
resolution
Type
string
Description
Provider-supported resolution such as 480p, 720p, 1080p, 4k
Name
aspect_ratio
Type
string
Description
Provider-supported ratio such as 16:9, 9:16, 1:1, 4:3, 3:4, 21:9
Name
audio
Type
boolean
Description
Include audio track when the model supports it
Name
webhook_url
Type
string
Description
URL for terminal state callbacks
Name
metadata
Type
object
Description
Client pass-through metadata

Current Venice-backed examples include venice-runway-gen4-5-text, venice-seedance-2-fast-t2v, and venice-pixverse-c1-t2v. Query /v1/models and /api/markets for the live catalog and active order book.

Idempotency: Include Idempotency-Key header to prevent duplicate submissions.

Response — 202 Accepted

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "media.job",
  "kind": "video",
  "status": "queued",
  "created": 1713200000,
  "expires_at": 1713201800,
  "estimated_cost_usdc": "102000",
  "max_cost_usdc": "112200",
  "poll_url": "/v1/video/generations/550e8400-...",
  "cancel_url": "/v1/video/generations/550e8400-...",
  "job_token": "mjt_abc123..."
}

Image-to-Video

Pass a source image to animate a still (image-to-video), interpolate between two stills (transition), or condition on reference frames.

Discovering models: image-to-video models carry an -image-to-video id suffix (e.g. seedance-2-0-image-to-video, wan-2-7-image-to-video, seedance-1-5-pro-image-to-video) and list image-to-video in their supported_parameters. Query /v1/models and /api/markets for the live set.
Required input: an image-to-video-only model (no text-to-video) requires a source image; a request without one returns 400. Transition models require both a start and an end frame.
Frames & roles: the simplest form is a single image_url (the start frame). For a transition, add end_image_url, or use input_images with explicit roles. Untagged input_images are positional — [start] or [start, end]; with three or more images, tag each with a role. Roles a model doesn't support are ignored — an extra frame won't fail the request.
Source form: https:// URL or data: URI; bare base64 (without the data: prefix) and http:// URLs are rejected. URLs are passed to the provider as-is — the marketplace never fetches them.

Image-to-video submit

json

{
  "model": "seedance-2-0-image-to-video",
  "prompt": "slow dolly-in as the waves roll",
  "image_url": "https://example.com/first-frame.png",
  "duration_seconds": 5
}

Poll Status

GET/v1/video/generations/:id

Auth: API key OR X-Job-Token header (returned from submit).

Status values: queued → submitted → running → succeeded | failed | canceled | expired.

Response — 202 (pending) or 200 (terminal)

json

{
  "id": "550e8400-...",
  "object": "media.job",
  "kind": "video",
  "status": "succeeded",
  "created": 1713200000,
  "expires_at": 1713201800,
  "progress": 1.0,
  "results": [
    {
      "artifact_index": 0,
      "url": "https://media-artifacts.s3.amazonaws.com/async-media/550e8400/0.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=…",
      "download_url": "/v1/media/artifacts/550e8400-.../0",
      "content_type": "video/mp4",
      "duration_seconds": 10,
      "width": 1920,
      "height": 1080,
      "bytes": 5000000
    }
  ],
  "usage": {
    "seller_cost_usdc": "80000",
    "buyer_cost_usdc": "96000",
    "settlement_status": "confirmed"
  }
}

Cancel Job

DELETE/v1/video/generations/:id

Auth: API key OR X-Job-Token header.

Cancellation is best-effort. If the provider has already completed the job, it may transition to succeeded instead.

Cost Model

Costs are USDC microdollars (1 USD = 1,000,000 microdollars).
Download artifacts are cached/proxied for buyer access. Default artifact retention is 3 hours (MEDIA_ARTIFACT_TTL_SECONDS can override it).
Seller selection uses the provider /video/quote endpoint with decrypted seller credentials; cost-multiplier offers apply the multiplier to the live quote.
estimated_cost_usdc is the buyer estimate at submit time.
max_cost_usdc is the reservation ceiling (estimated + 10% buffer).
Jobs expire after 30 minutes if not completed. Completed artifact download retention defaults to 3 hours.