Video Lab API

Quick start: generate, poll, download

Submit a prompt, poll the returned job_id every 2–5 seconds, then GET the returned video path.

BASE=http://127.0.0.1:7862
JOB=$(curl -fsS "$BASE/api/generate" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"t2v","prompt":"A paper boat drifting through a sunlit stream","aspect":"16:9","quality":"preview","duration":5,"turbo":true,"steps":6,"seed":-1}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["job_id"])')

curl -fsS "$BASE/api/jobs/$JOB" | python3 -m json.tool
# When status is complete, download the returned video URL.
curl -f "$BASE$(curl -fsS "$BASE/api/jobs/$JOB" | python3 -c 'import json,sys; print(json.load(sys.stdin)["video"])')" -o result.mp4

Endpoints

GET /api/config — capabilities and health

Returns installed FL2VA and Ref2VA assets, backend health, LoRAs, aspects, qualities and durations. The optional DaSiWa Hybrid V2 profile advertises its checkpoint and matching Turbo LoRA separately; it can be selected for T2V, I2V or Ref2VA while checkpoint:"auto" keeps the existing mode-specific model defaults.

{
  "model": "minimax_h3_fl2va_pruned_int8_convrot.safetensors",
  "backend_ready": true,
  "turbo_available": true,
  "turbo_lora": "minimax_h3_turbo_v4_step600_ema_pruned_comfyui.safetensors",
  "ref2va_model": "minimax_h3_ref2va_pruned_int8_convrot.safetensors",
  "ref2va_available": true,
  "ref2va_turbo_lora": "minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors",
  "ref2va_turbo_available": true,
  "hybrid_model": "DasiwaMinimaxH3_dasiwaHybridV2_3203130.safetensors",
  "hybrid_available": true,
  "hybrid_turbo_lora": "minimax_h3_fl2va_bf16_turbo_multistep_fro099_r48_pruned.safetensors",
  "hybrid_turbo_available": true,
  "loras": [{"id":"mystic-xxx-v4","name":"Mystic XXX v4 (FL2VA)","default_strength":1.0}],
  "aspects": ["16:9","9:16","1:1","4:3","3:4","21:9"],
  "qualities": ["draft","preview","native"],
  "durations": [4,5,6,8,10,12,15]
}

backend_ready is a point-in-time ComfyUI health check; retry if false.

POST /api/upload/{kind} — upload one Ref2VA reference

Upload raw file bytes to /api/upload/image, /api/upload/video, or /api/upload/audio. Set the X-File-Extension header (for example png or mp4); the server validates the file signature and returns an opaque id for a later generation request. Uploads are stored in ComfyUI's input directory and, when used for a Ref2VA generation, copied into that generation's persistent gallery storage.

Each reference video is split into frames and its soundtrack is automatically paired when present; use videos of 2–15 seconds. Tags follow ComfyUI's order: all images as <Picture 1>, then for each video its paired soundtrack as the next <Audio n> followed by <Video n>, then standalone audio clips. The official Ref2V Turbo LoRA's safetensors metadata names the original FL2VA BF16 base; Comfy-Org's official Ref2VA workflow explicitly uses this separately named Ref2V LoRA with the Ref2VA checkpoint. The FL2VA Turbo LoRA is never substituted. Browser uploads are same-origin; file IDs cannot select arbitrary paths.

POST /api/generate — enqueue a generation

Send JSON with Content-Type: application/json. Maximum request size is 30 MiB. Returns HTTP 202 with a job ID and normalized settings. The service supports one active ComfyUI generation at a time; additional requests may wait in ComfyUI's queue.

Example Ref2VA body (replace the ID with one returned from an upload):

{"mode":"ref2va","prompt":"Use <Picture 1> for the character identity and <Video 1> for motion. Preserve <Audio 1> as the voice reference.","aspect":"16:9","quality":"preview","duration":5,"turbo":true,"steps":4,"seed":-1,"ref_images":["h3-lab-ref-…png"],"ref_videos":[],"ref_audios":["h3-lab-ref-…wav"],"ref_image_size":"match"}

To use DaSiWa Hybrid V2 instead, add "checkpoint":"dasiwa-hybrid-v2" to either an FL2VA request or this Ref2VA request. In Hybrid Turbo mode, set steps from 4 to 8; 8 is recommended. The rank-48 Hybrid LoRA uses Euler/simple. Standard Hybrid sampling uses the checkpoint without a Turbo LoRA.

GET /api/jobs/{job_id} — poll status

Poll until the response is complete or error:

{"status":"running"}
{"status":"complete","video":"/api/video?filename=…&subfolder=H3Lab"}
{"status":"error","error":"…"}

Completed results are returned only after ComfyUI has saved the output. Invalid job IDs return 400; unavailable ComfyUI returns 502.

GET /api/gallery — recent saved generations

Returns every persisted generation newest first; the lab applies no gallery count limit and does not delete completed output files. Ref2VA reference files are copied into persistent per-generation gallery storage and shown inline; seeds are serialized as strings to preserve full 64-bit precision. The gallery's Reuse settings action automatically restores the archived references for repeat generation. POST /api/gallery/{gallery_id}/references performs that restore and returns new upload IDs. GET /api/gallery/{gallery_id}/reference/{kind}/{index} streams an individual saved input; kind is images, videos, or audios.

GET /api/video?filename=…&subfolder=H3Lab — stream/download

Use the relative video URL returned by a job or gallery item. Supports HTTP byte ranges for browser playback and resume.

POST /api/interrupt — stop generation

Send JSON body {}. This invokes ComfyUI's global interrupt endpoint and is not scoped to one job.

Errors and licensing

• Invalid fields, missing uploads or unavailable model assets: HTTP 400.
• ComfyUI rejects a workflow or is unavailable: HTTP 502.
• POST requests must be same-origin when an Origin header is supplied. No authentication is configured; do not expose the service directly to the public internet.
• The Ref2VA checkpoint is a separate 21 GB file; the installed FL2VA checkpoint cannot substitute. Automatic Ref2VA Turbo uses its separate official R2V LoRA. Optional DaSiWa Hybrid V2 is one checkpoint profile for FL2VA and Ref2VA, with its matching rank-48 Turbo LoRA; obtain both from Civitai and follow the creator's terms and MiniMax H3 Community License.
• MiniMax requires a commercial license for commercial use of locally generated H3 output. Check current model/LoRA terms before use.