视频生成

通过文本或图像生成 AI 视频（异步接口）

视频生成 API 允许你将图片或文本提示词转换为动态视频。

异步接口提示
由于生成视频需要大量算力及较长的处理时间，为避免平台（如 Cloudflare Workers）的请求超时限制，此接口被设计为完全异步。请求后会立即返回一个 taskId，而不是直接返回视频文件。你需要使用该 taskId 去查询最终结果，或者通过传入 webhookUrl 接收回调。

接口路径

POST /api/ai/videos

请求格式

与图像 API 相同，视频 API 完美支持 JSON 和 multipart/form-data 两种格式，允许你在请求中直接上传本地图片（如首尾帧）而无需繁琐的 base64 转换。

请求参数

prompt (String, 必填)

视频内容的文本描述。最大长度：3000字符。

model (String, 必填)

视频生成模型。

image (File/URL, 选填)

用于生成视频的参考图片（例如首尾帧）。在 multipart/form-data 中支持多个文件数组。

size (String, 选填)

输出尺寸。

webhookUrl (String, 选填)

强烈推荐。提供此 URL 后，一旦视频生成完成，系统会自动向该地址发送 POST 请求，推送包含最终视频 URL 和 taskCostTime 等信息的通知。

callback_url (String, 选填)

webhookUrl 的别名。

请求示例

curl -X POST "https://qxan.net/api/ai/videos" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "让这幅画中的水流运动起来",
"model": "runninghub-i2v-v1",
"image": ["https://example.com/path/to/start-frame.jpg"],
"webhookUrl": "https://your-server.com/webhook/video"
}'

curl -X POST "https://qxan.net/api/ai/videos" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "prompt=让这幅画中的水流运动起来" \
-F "model=runninghub-i2v-v1" \
-F "image=@/path/to/start-frame.jpg"

const formData = new FormData();
formData.append("prompt", "让这幅画中的水流运动起来");
formData.append("model", "runninghub-i2v-v1");
formData.append("image", fileInput.files[0]); // 直接上传图片作为首帧

const response = await fetch('https://qxan.net/api/ai/videos', {
method: 'POST',
headers: {
'Authorization': \`Bearer YOUR_API_KEY\`
},
body: formData
});

const data = await response.json();
console.log("Task ID:", data.id);

响应示例

成功提交任务后，你会收到包含任务标识符的响应。

{
  "id": "2044657634195480577",
  "status": "pending",
  "message": "Task queued successfully. Use the Task ID to query the status."
}

最佳实践

要高效处理视频生成，请按照以下步骤：

提交任务：向 /api/ai/videos 发送请求，并保存返回的 id。
获取结果：
- 方案 A (轮询)：每隔 5 秒调用一次任务状态 API 查询该 id 的状态。
- 方案 B (Webhook)：在初始请求中带上 webhookUrl 参数。系统将在任务完成时主动推送结果给你。

Webhook 回调详解

当任务完成时（成功或失败），系统会向您设置的 webhookUrl 发送 POST 请求。

成功响应

{
  "id": "2044657634195480577",
  "object": "task_result",
  "created": 1709880000,
  "status": "success",
  "result": {
    "images": [
      {
        "fileUrl": "https://rh-images.xiaoyaoyou.com/1fed4ce62b6a35e17d9103980f90ef6a/output/ComfyUI_00001_ynbbq_1776760390.png",
        "fileType": "png"
      }
    ]
  },
  "error": null
}

失败响应

{
  "id": "2044657634195480577",
  "object": "task_result",
  "created": 1709880000,
  "status": "failed",
  "result": {
    "images": []
  },
  "error": "Task processing failed: insufficient resources"
}

字段说明

字段	类型	说明
`id`	String	任务ID，与提交时返回的 `id` 一致
`object`	String	固定值 `"task_result"`
`created`	Integer	服务器收到结果的时间戳（Unix秒）
`status`	String	任务状态：`success` 或 `failed`
`result.images`	Array	生成的文件数组，包含 `fileUrl`（文件地址）和 `fileType`（文件类型，如 `png`、`mp4`）
`error`	String/null	失败原因，成功时为 `null`

On this page