HTTP API
動画生成
JSON または multipart で、テキストから動画、参照から動画、最初/最後のフレームを使ったタスクを実行します。
タスクを送信する
POST /api/v1/videos/generationsこのエンドポイントは application/json または multipart/form-data を受け付けます。ローカルの参照ファイルをアップロードする場合は multipart を、すべての入力が URL や短いフィールドで済む場合は JSON を使用します。
リクエストフィールド
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
model | string | はい | カタログの動画モデル ID。 |
prompt | string | はい | クリップで起こる内容。 |
variant | string | いいえ | モデルのバリアント。例：fast、2.0、2.5。 |
workflowFormat | string | いいえ | t2v（テキスト）、r2v（参照）、fl2v（最初/最後のフレーム）。 |
duration | string | いいえ | クリップの長さ（秒）。例：5、10。durationOptions に含まれている必要があります。 |
fps | string | いいえ | フレームレート。例：24。fpsOptions に含まれている必要があります。 |
size | string | いいえ | 出力解像度。例：1280x720。 |
ratio | string | いいえ | アスペクト比。例：16:9、9:16、1:1。 |
quality | string | いいえ | standard または high。 |
seed | number | いいえ | 再現性のためのシード値。 |
referenceImages | array | いいえ | 参照画像。JSON では URL、multipart ではファイル。 |
referenceVideos | array | いいえ | 参照動画。入力ルールは同じです。 |
referenceAudios | array | いいえ | 参照音声。入力ルールは同じです。 |
firstFrame / firstFrameUrl | file / string | いいえ | 開始フレーム。 |
lastFrame / lastFrameUrl | file / string | いいえ | 終了フレーム。 |
利用できるモデル、サイズ、長さ、ワークフローフォーマットはモデルごとに異なります。ハードコードせず、カタログから読み取ってください。
例（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"
}'例（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"レスポンス 202 Accepted
{
"ok": true,
"generation": {
"id": "vid_9c31be...",
"status": "generating",
"cost": 120,
"size": "1280x720",
"duration": 6,
"aspectRatio": "16:9",
"fps": 24
}
}| フィールド | 説明 |
|---|---|
generation.cost | このタスクで消費されたクレジット。 |
generation.size | 出力解像度。 |
generation.duration | クリップの長さ（秒）。 |
generation.aspectRatio | 正規化されたアスペクト比。 |
generation.fps | フレームレート。 |
タスクをポーリングする
GET /api/v1/videos/generations/{id}{
"ok": true,
"generation": {
"id": "vid_9c31be...",
"status": "success",
"error": null,
"durationMs": 184000,
"videoUrls": ["https://imagedelivery.net/.../public"]
}
}動画タスクは通常数分かかります。5 秒間隔でポーリングし、ステータスが success または failed になったら停止してください。
モデルカタログ
GET /api/v1/videos/modelsこのエンドポイントは公開されており、現在プラットフォームで利用可能なモデルのみを返します。
{
"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" }]
}
]
}長さ、サイズ、バリアント、参照数の上限は必ずこのレスポンスから読み取ってください。あるモデルで有効な値が、別のモデルでは 400 INVALID_VIDEO_REQUEST で拒否されることがよくあります。
補足
- 一時的に無効化されている動画モデルは、送信時に
503 MODEL_UNAVAILABLEを返し、カタログにも表示されません。 qualityは検証されますが、すべてのモデルが使用するわけではありません。非対応の組み合わせは400ですぐに失敗します。- 失敗したタスクのクレジットは自動的に返還され、成功したタスクは 1 回だけ課金されます。再試行用のエンドポイントはないため、新しいタスクを送信してください。