异步视频与 Flow 图片生成

词元 API 使用异步任务接口生成视频。部分 Flow 图片模型也通过同一接口提交，创建任务后需要轮询结果。

本文示例使用 https://code.ciyuanapi.xyz。code1、code2、code3 节点使用相同协议。

功能	方法与路径
查询可用模型	GET /v1/models
创建任务	POST /v1/videos
查询任务	GET /v1/videos/{task_id}
下载结果	GET /v1/videos/{task_id}/content

所有请求都需要词元 API Key：

Authorization: Bearer $API_KEY

模型、规格与价格

公开模型名	时长与价格	参考素材
MiniMax-H3	4-15 秒；768P $0.18/秒，2K $0.25/秒	图片最多 9 张，前 5 张免费，第 6-9 张 $0.10/张；参考视频最多 3 条、合计不超过 15 秒，768P $0.15/秒，2K $0.20/秒；参考音频最多 3 条免费
veo-3-1	固定 8 秒，$0.56/次	支持首尾帧和多图参考，最多 9 张图片
veo-omni-flash	固定 10 秒，$0.70/次	支持多图参考，最多 9 张图片
veo-omni-flash-video-edit	固定 10 秒，$1.00/次	必须提供 1 个最长 15 秒的参考视频，可附加最多 9 张参考图
nano-banana-pro-flow	$0.03/次	支持最多 8 张参考图，返回图片
nano-banana-2-flow	$0.03/次	支持最多 8 张参考图，返回图片

价格按请求参数计算。分组倍率、订阅或活动折扣会按账户实际规则应用。

MiniMax H3

MiniMax H3 支持 4-15 秒、768P/2K 输出以及图片、视频、音频参考素材。resolution 同时决定输出视频和参考视频的计费档位。

文生视频

curl https://code.ciyuanapi.xyz/v1/videos \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: h3-text-001" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "雨夜城市街道，电影感镜头缓慢向前推进",
    "duration": 8,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }'

多素材生成

参考视频必须同时提供对应的实际时长，数组顺序一一对应：

curl https://code.ciyuanapi.xyz/v1/videos \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: h3-reference-001" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "参考图片中的角色，采用参考视频的运镜并配合参考音频节奏",
    "duration": 10,
    "resolution": "2K",
    "aspect_ratio": "16:9",
    "reference_image_urls": [
      "https://cdn.example.com/character-1.jpg",
      "https://cdn.example.com/character-2.jpg"
    ],
    "reference_videos": [
      "https://cdn.example.com/camera.mp4"
    ],
    "reference_video_durations": [5.5],
    "reference_audios": [
      "https://cdn.example.com/music.mp3"
    ]
  }'

字段	类型	必填	说明
model	string	是	MiniMax-H3
prompt	string	是	视频描述
duration	integer	否	4-15，默认 4
resolution	string	否	768P 或 2K，默认 768P
aspect_ratio	string	否	例如 16:9、9:16；默认自适应
reference_image_urls	string[]	否	最多 9 张；第 6 张开始加收图片参考费
reference_videos	string[]	否	最多 3 条，总时长不超过 15 秒
reference_video_durations	number[]	条件必填	有参考视频时必填，单位秒，顺序必须与 reference_videos 一致
reference_audios	string[]	否	最多 3 条，免费

计费示例：8 秒 2K 输出、6 张参考图、1 条 5 秒参考视频，总价为 8 × $0.25 + 1 × $0.10 + 5 × $0.20 = $3.10。

VEO 3.1

veo-3-1 固定生成 8 秒视频。duration 可省略；如传入必须为 8。

文生视频

curl https://code.ciyuanapi.xyz/v1/videos \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: veo31-text-001" \
  -d '{
    "model": "veo-3-1",
    "prompt": "产品在柔和灯光下缓慢旋转，电影级质感",
    "duration": 8,
    "aspect_ratio": "16:9"
  }'

首尾帧

首图和尾图按数组顺序传入，并指定 function_mode：

{
  "model": "veo-3-1",
  "prompt": "从清晨平滑过渡到夜晚，保持镜头位置一致",
  "duration": 8,
  "aspect_ratio": "16:9",
  "images": [
    "https://cdn.example.com/first.jpg",
    "https://cdn.example.com/last.jpg"
  ],
  "metadata": {
    "function_mode": "first_last_frames"
  }
}

多图参考

{
  "model": "veo-3-1",
  "prompt": "组合这些参考素材生成统一风格的品牌短片",
  "duration": 8,
  "aspect_ratio": "9:16",
  "Ingredients_images": [
    "https://cdn.example.com/ref-1.jpg",
    "https://cdn.example.com/ref-2.jpg"
  ]
}

images、Ingredients_images 以及首尾帧图片去重后合计最多 9 张。

VEO Omni Flash

veo-omni-flash 固定生成 10 秒视频。duration 可省略；如传入必须为 10。

curl https://code.ciyuanapi.xyz/v1/videos \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: omni-flash-001" \
  -d '{
    "model": "veo-omni-flash",
    "prompt": "把参考产品图组合成节奏明快的广告视频",
    "duration": 10,
    "aspect_ratio": "16:9",
    "Ingredients_images": [
      "https://cdn.example.com/product-1.jpg",
      "https://cdn.example.com/product-2.jpg"
    ]
  }'

参考图去重后最多 9 张。

VEO Omni Flash 视频编辑

veo-omni-flash-video-edit 固定输出 10 秒，必须传入一个参考视频。参考视频最长 15 秒，可同时传入最多 9 张参考图。

curl https://code.ciyuanapi.xyz/v1/videos \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: omni-edit-001" \
  -d '{
    "model": "veo-omni-flash-video-edit",
    "prompt": "保留原视频动作，把场景改成明亮的未来城市",
    "duration": 10,
    "video_url": "https://cdn.example.com/input.mp4",
    "reference_video_duration": 12.4,
    "Ingredients_images": [
      "https://cdn.example.com/style.jpg"
    ]
  }'

字段	类型	必填	说明
video_url	string	是	唯一的参考视频 URL
reference_video_duration	number	建议	参考视频实际时长，单位秒；超过 15 秒会被拒绝
Ingredients_images	string[]	否	最多 9 张参考图
duration	integer	否	固定为 10

Nano Banana Flow 图片

nano-banana-pro-flow 和 nano-banana-2-flow 通过异步任务接口生成图片，每次 $0.03。它们不是视频模型，计费不随 duration 增加。

curl https://code.ciyuanapi.xyz/v1/videos \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: banana-flow-001" \
  -d '{
    "model": "nano-banana-pro-flow",
    "prompt": "将参考图改成干净的产品摄影风格",
    "resolution": "2k",
    "aspect_ratio": "1:1",
    "images": [
      "https://cdn.example.com/reference.jpg"
    ]
  }'

公开模型名只使用 nano-banana-pro-flow 和 nano-banana-2-flow。每次最多 8 张参考图，完成任务的结果是图片。

查询任务

创建成功返回 HTTP 200 和公开任务 ID：

{
  "id": "task_0123456789abcdef",
  "object": "video",
  "status": "queued",
  "progress": 0,
  "model": "veo-3-1"
}

建议每 5-10 秒查询一次：

curl https://code.ciyuanapi.xyz/v1/videos/task_0123456789abcdef \
  -H "Authorization: Bearer $API_KEY"

状态	处理方式
queued	继续轮询
in_progress	继续轮询
completed	使用 metadata.url 获取结果
failed	停止轮询并读取 error.message
ambiguous	停止轮询并联系平台核对

完成响应示例：

{
  "id": "task_0123456789abcdef",
  "object": "video",
  "model": "veo-3-1",
  "status": "completed",
  "progress": 100,
  "metadata": {
    "url": "https://code.ciyuanapi.xyz/v1/videos/task_0123456789abcdef/content"
  }
}

下载结果仍需鉴权：

curl https://code.ciyuanapi.xyz/v1/videos/task_0123456789abcdef/content \
  -H "Authorization: Bearer $API_KEY" \
  -o result.bin

任务只能由所属用户查询和下载。请直接使用返回的完整 metadata.url。

JavaScript 轮询示例

const baseURL = "https://code.ciyuanapi.xyz"
const apiKey = process.env.CIYUAN_API_KEY

const submitResponse = await fetch(`${baseURL}/v1/videos`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    model: "veo-3-1",
    prompt: "海面上的灯塔，云层快速流动",
    duration: 8,
    aspect_ratio: "16:9",
  }),
})

if (!submitResponse.ok) throw new Error(await submitResponse.text())
const task = await submitResponse.json()

while (true) {
  await new Promise((resolve) => setTimeout(resolve, 5000))
  const response = await fetch(`${baseURL}/v1/videos/${task.id}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  })
  if (!response.ok) throw new Error(await response.text())
  const result = await response.json()

  if (result.status === "completed") {
    console.log("结果地址", result.metadata.url)
    break
  }
  if (["failed", "ambiguous"].includes(result.status)) {
    throw new Error(result.error?.message || `任务结束：${result.status}`)
  }
}

幂等、重试与结算

• 每个新任务使用唯一的 Idempotency-Key，最长 255 个字符。
• 相同用户、令牌、幂等键和完全相同的请求会返回原任务，不会重复创建或重复预扣。
• 同一幂等键对应不同请求时返回 HTTP 409 和 idempotency_conflict。
• 网络错误或 HTTP 429、502、503 时，只用相同幂等键和完全相同的请求做有限重试。
• HTTP 400、401、403、451 以及内容审核失败不应原样重试，应先调整参数或素材。
• 创建任务时预扣余额；明确失败会自动退款。
• ambiguous 不会自动结算或退款，需要人工核对上游结果。

常见错误

HTTP/错误码	说明
invalid_model	模型不存在或未对当前令牌开放
invalid_duration	模型时长不符合固定值或范围
invalid_request	参考素材数量、视频数量、分辨率或其他参数不符合要求
insufficient_user_quota	账户余额不足
idempotency_conflict / HTTP 409	幂等键已用于另一份请求
PROMPT_BLOCKED / HTTP 451	内容审核拒绝，需修改提示词或参考素材
HTTP 413	请求体或素材过大