Video Generation
Sume supports video generation from text prompts (and optional reference
images) via a dedicated asynchronous API. You can find the supported models,
their capabilities, and pricing from GET /v1/videos/models.
This surface follows the OpenRouter Video Generation API field-for-field, so a client written against their docs works here after changing the base URL and the API key. The handful of places Sume differs are collected in Sume differences.
Model Discovery
You can find video generation models in several ways:
Via the Video Models API
Use the dedicated video models endpoint to list all available video generation models along with their supported parameters:
The response returns a data array where each model includes:
| Field | Description |
|---|---|
id | Model slug to use in generation requests |
canonical_slug | Permanent model identifier |
supported_resolutions | List of supported output resolutions (e.g., 720p, 1080p) |
supported_aspect_ratios | List of supported aspect ratios (e.g., 16:9, 9:16) |
supported_sizes | List of supported pixel dimensions (e.g., 1280x720), or null |
supported_durations | Supported video lengths in whole seconds |
supported_frame_images | Which frame_type values the model accepts |
supported_input_references | Which input_references types the model accepts |
generate_audio | Whether the model can generate an audio track |
seed | Whether the model accepts a seed |
pricing_skus | Pricing information per SKU |
allowed_passthrough_parameters | Provider-specific parameters that can be passed through via the provider option |
Use this endpoint to check which resolutions, aspect ratios, and durations are
supported by each model before submitting a generation request. Limits are not
uniform: seedance-2.5 accepts 4–30 seconds at 480p/720p/1080p, wan-3.0
accepts 2–30 seconds, and minimax-h3 accepts 5–15 seconds at native 480p/768p
(768p is first-class, not 720p; 2K/4K upscales are priced if requested). Every
other catalog model tops out at 15 seconds. seedance-2 also offers 1080p.
MiniMax H3 Max (minimax-h3-max) is gated until GA and is not listed.
Via the Models API
You can also use the public model catalog to discover video generation models:
On the Models Page
Visit the Models page and look for models that list video as an
output modality.
How It Works
Unlike text or image generation, video generation is asynchronous because generating video takes significantly longer. The workflow is:
- Submit a generation request to
POST /v1/videos - Receive a job ID and polling URL immediately
- Poll the polling URL (
GET /v1/videos/{jobId}) until the status iscompleted - Download the video from the content URL (
GET /v1/videos/{jobId}/content)
API Usage
Submitting a Video Generation Request
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | The model to use for video generation (e.g., seedance-2.5), or sume/auto to let Sume pick |
prompt | string | Yes | Text description of the video to generate |
duration | integer | No | Duration of the generated video in seconds |
resolution | string | No | Resolution of the output video (e.g., 720p, 1080p) |
aspect_ratio | string | No | Aspect ratio of the output video (e.g., 16:9, 9:16, 3:2) |
size | string | No | Exact pixel dimensions in WIDTHxHEIGHT format (e.g., 1280x720). Interchangeable with resolution + aspect_ratio |
frame_images | array | No | Images for first/last frames (image-to-video) |
input_references | array | No | Reference images for style guidance (reference-to-video) |
generate_audio | boolean | No | Whether to generate audio alongside the video. Defaults to the model's audio capability |
seed | integer | No | Seed for deterministic generation (not guaranteed by all providers) |
callback_url | string | No | URL to receive a webhook notification when the job completes. Must be HTTPS |
provider | object | No | Provider-specific passthrough configuration |
Supported Resolutions
480p720p768p1080p1K2K4K
Each model advertises the subset it accepts in supported_resolutions.
Supported Aspect Ratios
16:9— Widescreen landscape9:16— Vertical/portrait1:1— Square4:3— Standard landscape3:4— Standard portrait3:2— Photography landscape2:3— Photography portrait21:9— Ultra-wide9:21— Ultra-tall
Each model advertises the subset it accepts in supported_aspect_ratios.
Using Images
There are two ways to provide images, each triggering a different generation mode:
frame_images— Specifies first or last frame images for image-to-video generation. Each entry must include aframe_typeoffirst_frameorlast_frame.input_references— Provides style or content reference images for reference-to-video generation. The model uses these as visual guidance rather than exact frames.
If both fields are provided, frame_images takes precedence and the request is
treated as image-to-video.
Image-to-Video (frame_images)
Reference-to-Video (input_references)
Only models whose supported_input_references lists a type accept that type.
Audio and video references are honored by Seedance 2.0 only.
Provider-Specific Options
You can pass provider-specific options using the provider parameter. Options
are keyed by provider slug, and only the options for the matched provider are
forwarded:
Use the Video Models API to check which passthrough
parameters each model supports via the allowed_passthrough_parameters field.
In v1 that list is empty for every model, so provider.options entries are
rejected rather than silently dropped — see
Sume differences.
Response Format
Submit Response (202 Accepted)
When you submit a video generation request, you receive an immediate response with the job details:
Poll Response
When polling the job status, the response includes additional fields as the job progresses:
Job Statuses
| Status | Description |
|---|---|
pending | The job has been submitted and is queued |
in_progress | The video is being generated |
completed | The video is ready to download |
failed | The generation failed (check the error field) |
cancelled | The job was canceled before it finished |
Downloading the Video
Once the job status is completed, the unsigned_urls array contains URLs to
download the generated video content. You can also use the content endpoint
directly:
The index query parameter defaults to 0 and can be used if the model
generates multiple video outputs.
Webhooks
Instead of polling for job status, you can receive a webhook notification when a
video generation job completes. Pass callback_url in the request body; Sume
POSTs to it once the job reaches a terminal state.
Sume signs the raw JSON body and sends x-sume-webhook-timestamp and
x-sume-webhook-signature headers. The payload is Sume's standard job webhook
envelope, not OpenRouter's video.generation.* envelope — see
Sume differences and the
webhooks guide for the exact shape and verification steps.
Sume differences
Everything above matches the OpenRouter Video Generation API. These are the only deltas.
| Area | OpenRouter | Sume |
|---|---|---|
| Base path | https://openrouter.ai/api/v1/videos | https://api.sume.com/v1/videos (no /api segment) |
| Auth | Authorization: Bearer $OPENROUTER_API_KEY | Authorization: Bearer $SUME_API_KEY |
| Model ids | org/slug (e.g. google/veo-3.1) | bare catalog ids (e.g. seedance-2). Sume's published contract never carries a provider-org prefix |
| Auto routing | no generate-time auto | model: "sume/auto" lets Sume pick the family. Responses echo sume/auto; the family that ran is never disclosed |
size | accepted where the model advertises supported_sizes | every v1 model reports supported_sizes: null, so size returns 400 unsupported_parameter. Use resolution + aspect_ratio |
provider.options | forwarded to the matched upstream provider | v1 runs a single backend per model, so a non-empty provider.options returns 400 unsupported_parameter |
seed | accepted by many models | no v1 model accepts seed; each reports seed: false and rejects the field |
| Webhook envelope | video.generation.* events, X-OpenRouter-Signature | Sume's standard job webhook envelope with x-sume-webhook-signature |
| Idempotency | none on this route | send Idempotency-Key to make retries safe; a replay returns the original job |
| Job lifecycle | polling URL only | the same job is also visible at GET /v1/jobs/{id}/status and GET /v1/jobs/{id}/result |
| Zero Data Retention | video generation is ZDR-ineligible | Sume has no ZDR toggle; see the privacy docs |
| Billing | credits | workspace USD balance, reserved on submit at provider list × 1.10. usage.cost is the Sume billable amount |
sume/auto
sume/auto is a Sume-only addition. Send it as model when you do not want to
pin a family:
Resolution is a pure function of the normalized request and the catalog
version, so an idempotent replay prices and routes identically. The poll
response reports "model": "sume/auto" — Sume does not disclose which family
served the request, and you should not build on any observable trait of the
output to infer it.
/v1/video-router/*
POST /v1/video-router/generate and GET /v1/video-router/models still work
unchanged and create the same jobs, with the same model ids. The difference is
the wire: Video Router returns Sume's { "data": ... } job envelope and takes
Sume's flat image_url / reference_image_urls fields, while /v1/videos
returns the response shape documented above. Because the model vocabulary is
shared, migrating is a path-and-body change with no id remapping. New
integrations should use /v1/videos.
Best Practices
- Detailed Prompts: Provide specific, descriptive prompts for better video quality. Include details about motion, camera angles, lighting, and scene composition
- Appropriate Resolution: Higher resolutions take longer to generate and cost more. Choose the resolution that fits your use case
- Polling Interval: Use a reasonable polling interval (e.g., 30 seconds) to avoid excessive API calls. Video generation typically takes 30 seconds to several minutes depending on the model and parameters
- Error Handling: Always check the job status for
failedstate and handle theerrorfield appropriately - Reference Images: When using reference images, ensure they are high quality and relevant to the desired video output
Troubleshooting
Job stays in pending for a long time?
- Video generation can take several minutes depending on the model, resolution, and server load
- Continue polling at regular intervals
Generation failed?
- Check the
errorfield in the poll response for details - Ensure your prompt is appropriate and within model guidelines
- Check that any reference images are accessible over public HTTPS and in supported formats
Model not found?
- Use the Video Models API to find available video generation models
- Verify the model id is correct (e.g.,
seedance-2) — Sume uses bare catalog ids, notorg/slug