Cosmos 3 Super Image to Video API Reference

Request body

Submit an async generation request. The model field selects the model; other fields are model-specific input parameters.

stringmodelrequired

Model identifier. Set to nvidia/cosmos-3-super/image-to-video.

Default: nvidia/cosmos-3-super/image-to-video

stringpromptrequired

Text prompt describing the motion and scene of the video to generate.

stringimagerequired

URL of the conditioning first-frame image for the video.

Optional<number>guidance_scale

Classifier-free guidance scale. Higher values increase prompt adherence at the cost of diversity.

Range: 0 to 20

Default: 6

Optional<integer>num_inference_steps

Number of denoising steps. More steps yield higher quality but take longer.

Range: 1 to 50

Default: 28

Optional<integer>agentic_samples_per_iteration

Candidate videos to generate and judge per agentic iteration. The best candidate advances to the next rewrite stage.

Range: 1 to 3

Default: 2

Optional<boolean>agentic_early_stop

Stop the agentic loop early when the critic score clears the strict quality threshold.

Default: true

Optional<boolean>enable_agentic_generation

Enable the iterative Cosmos agentic loop: prompt upsampling, candidate video generation, VLM critique of sampled frames, and prompt rewrite. Each candidate is a full render, so this is substantially slower and costlier than a single generation.

Default: false

Optional<integer>num_frames

Number of frames to generate. More frames yield a longer video.

Range: 5 to 189

Default: 189

Optional<integer>frames_per_second

Frames per second of the output video.

Range: 4 to 60

Default: 24

Optional<integer>agentic_max_iterations

Maximum agentic prompt stages when agentic generation is enabled.

Range: 1 to 3

Default: 2

Optional<string>aspect_ratio

The aspect ratio of the generated image.

Allowed values: 21:9, 16:9, 3:2, 4:3, 5:4, 1:1, 4:5, 3:4, 2:3, 9:16

Optional<integer>seed

The same seed and prompt given to the same model version will produce the same video every time.

Response Schema

The submit endpoint returns a run response. If its status is pending or running, poll GET /v1/run/{id} with the returned opaque ID until it reaches a terminal state.

stringidrequired

Opaque SandBase run identifier. Use it exactly as returned; no prefix is guaranteed.

stringstatusrequired

Current public run status.

Allowed values: pending, running, completed, failed, timeout

Optional<string>model

Public SandBase model name used for this run.

Optional<array<object>>outputs

Present only for completed runs. Each object is capability-specific; inspect the selected model schema for its fields.

Optional<object>error

Present only for failed or timeout runs. Contains a public error type and sanitized message.

Optional<string>error.type

Stable public error category.

Optional<string>error.message

Sanitized error message safe to show to clients.

Optional<object>usage

Usage details when available.

Model capabilities

array<string>capability_tagsrequired

Capabilities declared by the model registry.

Default: image-to-video

stringexecution_moderequired

Execution mode declared by the model registry.

Default: async

# 1. Submit a generation request curl -X POST https://api.sandbase.ai/v1/run \ -H "Authorization: Bearer $SANDBASE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "nvidia/cosmos-3-super/image-to-video", "prompt": "The camera slowly pushes in as the subject turns their head toward the light, hair drifting in a gentle breeze, dust motes floating through warm afternoon sun.", "image": "https://storage.googleapis.com/falserverless/example_inputs/hunyuan_i2v.jpg", "aspect_ratio": "21:9" }' # 2. If the response is still running, poll the returned id curl https://api.sandbase.ai/v1/run/f3d2e8a1-7c4b-4a12-9d2e-123456789abc \ -H "Authorization: Bearer $SANDBASE_API_KEY"