H3 Max Reference 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 minimax/h3-max/reference-to-video.

Default: minimax/h3-max/reference-to-video

stringpromptrequired

Text prompt for video generation. Refer to reference assets by their modality and order in the reference lists: Image 1, Image 2, Video 1, Audio 1, and so on.

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<string>resolution

The native generation resolution of the video.

Allowed values: 480P, 768P

Default: 768P

Optional<integer>duration

The duration of the video in seconds.

Range: 5 to 15

Default: 5

Optional<integer>seed

Random seed. A random seed is selected when omitted.

Optional<array<string>>reference_image_urls

URLs of subject/style reference images, referenced in the prompt as Image 1, Image 2, and so on. Reference images, videos, and audio clips must add up to at most 12 files.

Optional<string>prompt_expansion_mode

How much effort to spend rewriting the prompt before generation. 'balanced' returns in about a second. 'quality' spends up to ~30s on a richer prompt.

Default: balanced

Optional<array<string>>reference_video_urls

URLs of motion/reference video clips (2-15 seconds each, combined duration at most 15 seconds), referenced in the prompt as Video 1, Video 2, and so on. Reference images, videos, and audio clips must add up to at most 12 files.

Optional<array<string>>reference_audio_urls

URLs of reference audio clips (2-15 seconds each, combined duration at most 15 seconds), referenced in the prompt as Audio 1, Audio 2, and so on. Audio cannot be the only reference input; provide at least one reference image or video with it. Reference images, videos, and audio clips must add up to at most 12 files.

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": "minimax/h3-max/reference-to-video", "prompt": "Image 1 is the female protagonist. Image 2 is her small dog. Keep the woman and dog consistent with their respective reference images while they walk together through a sunlit garden.", "aspect_ratio": "21:9", "duration": 5 }' # 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"