视频模型进阶用户更新于
POST/v1/videos/generations
flux-3-video
请求 ID flux-3-video
协议
POST /v1/videos/generations· 生成视频示例GET /v1/videos/tasks/{id}· 查询视频任务示例GET /v1/videos/tasks/{id}/content· 下载视频示例DELETE /v1/videos/tasks/{id}· 删除已结束的视频任务示例POST /v1/videos/assets· 上传素材示例DELETE /v1/videos/assets/{id}· 删除素材示例
认证
请求需要 API Key。在控制台的 API Key 管理 获取密钥。发送 JSON 请求时，设置 Content-Type: application/json。
Authorization: Bearer YOUR_API_KEY
请求参数
POST /v1/videos/generations
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
model | string | 必填 | flux-3-video. 使用本页列出的模型 ID。 |
prompt | string | 视条件 | 描述画面、动作和镜头。 常规生成必填，草稿增强时省略。 |
content | array<object> | 视条件 | 参考素材和可选文本项。仅传 prompt 做文生视频时可省略。 最多 10 张图片。 首帧、中间参考图、尾帧按列表顺序提交。视频编辑使用一个 3–30 秒的视频。 |
content[].type | string | 必填 | 可用值为 text, image_url, input_image, video_url, input_video。 |
content[].text | string | 视条件 | 当素材项的 type 为 text 时填写提示词。 |
content[].role | string | 视条件 | 首帧用 first_frame，尾帧用 last_frame。尾帧要求同时提供首帧。 普通参考图用 reference_image。 参考视频使用 reference_video。 |
content[].asset_id | string | 视条件 | 先用 POST /v1/videos/assets 上传素材，再填返回的 id。在 multipart 表单中先填 kind（image, video），再填 file。 |
resolution | string | 选填 | 可用值为 hd, fhd。 默认 hd。 |
ratio | string | 选填 | 输出宽高比，兼容字段名 aspect_ratio。 可用值为 auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16。 默认 auto。 |
duration | integer | 选填 | 输出时长，单位为秒。 接受 5–20 秒的整数。 默认 5。 |
generate_audio | boolean | 选填 | 是否生成音轨。 默认 true。 |
generation_mode | string | 选填 | 可用值为 auto, t2v, i2v, v2v, draft_enhance。 默认 auto，根据素材选择模式。显式模式须与素材匹配。 |
draft | boolean | 选填 | true 生成可增强的草稿，仅支持 hd。 |
source_task_id | string | 视条件 | 草稿增强时必填。使用本人已成功完成并结算的同模型草稿 ID。该模式只传 model、generation_mode、source_task_id 和 resolution。 |
请求示例
先将 API Key 设置为本机环境变量 ICODEEASY_API_KEY，并选择支持直接 HTTP 调用的接入点。接入点要求特定客户端时，按对应客户端指南配置。
示例中的素材 URL 和素材 ID 需要替换成自己的有效素材。
Video Generations
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/generations' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"model": "flux-3-video",
"prompt": "Slow camera push toward a paper lantern swaying gently by a lake.",
"resolution": "hd",
"ratio": "16:9",
"duration": 5
}'
查询视频任务
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY"
下载视频
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID/content' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-L \
-o result.mp4
删除已结束的视频任务
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-i \
-X DELETE
上传素材
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/assets' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-F 'kind=image' \
-F '[email protected];type=image/png'
上传素材 · 上传视频
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/assets' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-F 'kind=video' \
-F '[email protected];type=video/mp4'
删除素材
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/assets/YOUR_ASSET_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-i \
-X DELETE
响应与任务
HTTP 202 · 任务已受理
json
{
"id": "vid_1785398400000000000",
"object": "video.generation.job",
"model": "flux-3-video",
"created_at": "2026-07-30T08:00:00Z",
"status_url": "/v1/videos/tasks/vid_1785398400000000000",
"content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
"status": "queued",
"updated_at": "2026-07-30T08:00:00Z",
"task_id": "vid_1785398400000000000"
}
HTTP 200 · 查询到已完成任务
json
{
"id": "vid_1785398400000000000",
"object": "video.generation.job",
"model": "flux-3-video",
"created_at": "2026-07-30T08:00:00Z",
"status_url": "/v1/videos/tasks/vid_1785398400000000000",
"content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
"status": "succeeded",
"updated_at": "2026-07-30T08:01:00Z",
"url": "/v1/videos/tasks/vid_1785398400000000000/content"
}
保存 id。用同一 API Key 对 status_url 发起 GET 请求，直到 status 变为 succeeded 或 failed。成功后请求 content_url 下载，并允许 HTTP 重定向。两个地址都相对于 API Base URL。
| 字段 | 类型 | 说明 |
|---|---|---|
id / task_id | string | 任务 ID。创建响应中的 task_id 与 id 相同。 |
status | string | 任务状态，可为 queued、running、succeeded 或 failed。 |
progress | integer | 生成进度。服务没有进度值时会省略。 |
error.code | string | 生成失败时返回错误分类。 |
常见错误
| HTTP | 错误类型 | 说明 |
|---|---|---|
| 400 | invalid_request | 检查模型、字段组合和参考素材是否有效。 |
| 401 | unauthorized | 检查 API Key 是否缺失、无效或已停用。 |
| 402 | insufficient_balance | 账户余额不足以提交任务。 |
| 404 | not_found | 查询遇到 404 时保留任务 ID，核对任务所属账户的 API Key 和查询地址。任务可能已完成，请勿因此重新提交。 |
| 409 | video_not_ready | 视频尚未生成完成。继续查询任务状态。 |
| 503 | submission_unknown | 无法确认提交结果。请先联系支持确认任务是否已创建，再提交新请求。 |
完整接入指南 · 查看完整接口指南，了解请求字段、任务状态和响应格式。
能力与限制
text_to_video· 支持image_to_video· 支持first_frame· 支持last_frame· 支持reference_images· 支持video_input· 支持audio· 支持- 限制 分辨率: hd, fhd · 画面比例: auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16 · 参考图：最多 10 张 · 时长: 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20 · 输入：Site images ≤10 MB; videos ≥3s. One video ≤30s. Owned completed HD draft enhancement; ordered first/intermediate/last keyframes, duplicates preserved.