HTTP API
Video generation
Text-to-video, reference-to-video and first/last-frame tasks over JSON or multipart.
Submit a task
POST /api/v1/videos/generationsThe endpoint accepts application/json or multipart/form-data. Use multipart when you upload local reference files; use JSON when every input is already a URL or a short field.
Request fields
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Video model ID from the catalog. |
prompt | string | Yes | What happens in the clip. |
variant | string | No | Model variant, e.g. fast, 2.0, 2.5. |
workflowFormat | string | No | t2v (text), r2v (references) or fl2v (first/last frame). |
duration | string | No | Clip length in seconds, e.g. 5, 10; must be in durationOptions. |
fps | string | No | Frame rate, e.g. 24; must be in fpsOptions. |
size | string | No | Output resolution, e.g. 1280x720. |
ratio | string | No | Aspect ratio, e.g. 16:9, 9:16, 1:1. |
quality | string | No | standard or high. |
seed | number | No | Reproducibility seed. |
referenceImages | array | No | Reference images: URLs in JSON, files in multipart. |
referenceVideos | array | No | Reference videos, same input rules. |
referenceAudios | array | No | Reference audio, same input rules. |
firstFrame / firstFrameUrl | file / string | No | Opening frame. |
lastFrame / lastFrameUrl | file / string | No | Closing frame. |
Available models, sizes, durations and workflow formats differ per model — read them from the catalog instead of hard-coding.
Example (JSON)
curl -X POST https://imagifly.net/api/v1/videos/generations \
-H "Authorization: Bearer $IMAGIFLY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-H3",
"prompt": "A paper boat drifting down a rain-soaked street, neon reflections",
"duration": "6",
"ratio": "16:9"
}'Example (multipart)
curl -X POST https://imagifly.net/api/v1/videos/generations \
-H "Authorization: Bearer $IMAGIFLY_API_KEY" \
-F "model=MiniMax-H3" \
-F "prompt=Slow push-in on the character, wind in the hair" \
-F "workflowFormat=fl2v" \
-F "duration=5" \
-F "firstFrame=@./first.png" \
-F "lastFrame=@./last.png"Response 202 Accepted
{
"ok": true,
"generation": {
"id": "vid_9c31be...",
"status": "generating",
"cost": 120,
"size": "1280x720",
"duration": 6,
"aspectRatio": "16:9",
"fps": 24
}
}| Field | Description |
|---|---|
generation.cost | Credits charged for this task. |
generation.size | Output resolution. |
generation.duration | Clip length in seconds. |
generation.aspectRatio | Normalized aspect ratio. |
generation.fps | Frame rate. |
Poll a task
GET /api/v1/videos/generations/{id}{
"ok": true,
"generation": {
"id": "vid_9c31be...",
"status": "success",
"error": null,
"durationMs": 184000,
"videoUrls": ["https://imagedelivery.net/.../public"]
}
}Video tasks usually take minutes. Poll every 5 seconds and stop when the status is success or failed.
Model catalog
GET /api/v1/videos/modelsThis endpoint is public and only returns models that are currently available on the platform.
{
"ok": true,
"models": [
{
"id": "MiniMax-H3",
"label": "MiniMax H3",
"credits": 120,
"aspectRatios": ["16:9", "9:16", "1:1"],
"resolutions": [{ "resolution": "720p", "size": "1280x720", "credits": 120 }],
"defaultSize": "1280x720",
"defaultDurationSeconds": 6,
"minDurationSeconds": 4,
"maxDurationSeconds": 10,
"durationOptions": [4, 5, 6, 8, 10],
"fpsOptions": [24],
"billingUnit": "second",
"mode": "text-to-video",
"referenceImageLimit": 0,
"referenceVideoLimit": 0,
"referenceAudioLimit": 0,
"workflowFormats": [{ "id": "t2v", "requiresFirstFrame": false }],
"variants": [{ "id": "fast", "label": "Fast", "credits": 90, "size": "1280x720" }]
}
]
}Always read durations, sizes, variants and reference limits from this response: a value that works for one model is often rejected by another with 400 INVALID_VIDEO_REQUEST.
Notes
- A video model that is temporarily disabled returns
503 MODEL_UNAVAILABLEon submit and is omitted from the catalog. qualityis validated but not every model uses it; unsupported combinations fail fast with400.- Failed tasks are refunded automatically; a successful task is charged once. There is no retry endpoint — submit a new task.