创建视频生成任务

创建异步视频任务。受理后返回任务 ID，再查询获取视频 URL。

请求地址

POSThttps://fablun.com/api/v3/contents/generations/tasks

请求头

参数	必填	说明
`Authorization`	是	`Bearer YOUR_API_KEY`
`Content-Type`	是	`application/json`
`Idempotency-Key`	否	建议提供。1～128 字符，仅字母、数字及 _.:-；同一次请求重试使用原值。

请求参数

参数	类型	必填	默认值	说明
`model`	string	是	—	h3-pro 或 h3-standard，需已对账户开放。
`content`	object[]	是	—	1～8 项，至少一项 text；可附一张 image_url 首帧。合并后的提示词最多 2000 字符。
`resolution`	string	否	480p	480p / 720p。建议显式传入，以模型规格为准。
`duration`	integer	否	5	单位秒。H3 Pro 的 480p 文生/图生支持 5、10、12 秒，720p 仅支持 5 秒；其他模型以“模型与规格”页为准。
`seed`	integer	否	-1	省略或 -1 为随机；可指定 0～2147483647，0 有效。查询返回实际种子。
`ratio`	string	否	16:9	1:1、3:4、4:3、16:9、9:16；H3 Pro 的 480p、720p 均支持，实际供给以已验收节点为准。
`generate_audio`	boolean	否	true	true 保留音频；false 返回静音视频，视频画面不重新编码。
`watermark`	boolean	否	false	当前固定为 false。
`service_tier`	string	否	default	仅支持 default，不支持 flex。
`execution_expires_after`	integer	否	172800	任务有效期，含排队，单位秒；3600～259200，受平台上限约束。
`priority`	integer	否	0	0～9。在账户公平调度、等待保护内决定优先级，不抢断推理。
`callback_url`	string	否	—	公网 HTTPS 回调地址；也可省略，直接轮询。
`safety_identifier`	string	否	—	最多 64 字符，自定义最终用户标识。

return_last_frame、camera_fixed、draft 仅接受 false。不支持的能力和未知字段返回 422。

content 对象

类型	字段	说明
text	`text`	必需的提示词，多段文字按换行合并。
image_url	`image_url.url`	公网图片 URL 或完整 Base64 data URL。
image_url	`role`	`first_frame` / `last_frame`；尾帧须配对首帧，限 H3 Pro · 5 秒。

JSON · 文本与首帧

{
  "content": [
    {
      "type": "text",
      "text": "镜头缓慢推进，人物自然微笑。"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_IMAGE_HOST/first-frame.jpg"
      },
      "role": "first_frame"
    }
  ]
}

请求示例

模型模式分辨率时长画幅Seed

Python · 创建并自动查询

import os, time, uuid
from volcenginesdkarkruntime import Ark

client = Ark(
    api_key=os.environ["ARK_API_KEY"],
    base_url="https://fablun.com/api/v3",
)

request_key = str(uuid.uuid4())  # 仅新任务生成；网络重试改用已保存的原值。
print("Idempotency-Key:", request_key)
task = client.content_generation.tasks.create(
    model="h3-pro",
    content=[
        {"type":"text","text":"清晨，一只蝴蝶落在白色雏菊上。微距镜头，柔和自然光。"}
    ],
    resolution="480p", duration=5, ratio="16:9",
    
    extra_headers={"Idempotency-Key": request_key},
)
print("task_id:", task.id)  # 保存 ID，网络中断后继续查询原任务。

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = client.content_generation.tasks.get(task_id=task.id)
    if result.status == "succeeded":
        print(result.content.video_url)
        break
    if result.status in ("failed", "expired", "cancelled"):
        raise RuntimeError(result.error or result.status)
    time.sleep(2)
else:
    raise TimeoutError(f"等待结束，请继续查询原任务：{task.id}")

响应参数

HTTP 200 · application/json

{
  "id": "cgt-0123456789abcdef0123456789abcdef"
}

字段	类型	说明
`id`	string	任务 ID，保存后用于查询、取消或排查。

HTTP 200 仅表示受理成功。视频 URL 在查询响应的 content.video_url 中。

首尾帧视频

H3 Pro · 5 秒支持首尾帧；480p / 720p 均支持 1:1、3:4、4:3、16:9、9:16。每种 role 仅一张，last_frame 必须与 first_frame 配对。按一条视频计费，取消、审核和完成回调沿用普通任务流程。return_last_frame 是输出末帧选项，尚未开放。

{
  "model": "h3-pro",
  "content": [
    {
      "type": "text",
      "text": "A red ball rolls from left to right."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_IMAGE_HOST/first-frame.jpg"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://YOUR_IMAGE_HOST/last-frame.jpg"
      },
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "duration": 5,
  "ratio": "16:9",
  "generate_audio": true
}

可选视频压缩

compress：boolean，默认 false。传 true 后在北京 CPU 交付阶段压缩，保留尺寸、帧率和音轨；不另收生成费用。未节省至少 5% 或编码失败时返回原片，并通过 compression.applied / reason 说明。结果完成后沿用普通审核、下载有效期和签名回调。

{
  "model": "h3-pro",
  "content": [
    {
      "type": "text",
      "text": "A cat walks through a garden."
    }
  ],
  "resolution": "720p",
  "compress": true
}