API · 2.0

视频生成 API 文档

文生视频、图生视频、任务查询与视频下载接口说明

开始接入查看 Markdown

视频生成网关 API 文档

版本：2.0
基础地址：https://api.tiaotiao.shop

本文档只描述网关对外接口。所有生成结果均返回本网关地址。

1. 鉴权

所有 /v1/* 接口建议使用 Bearer Token：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

兼容模式也支持查询参数：

?api_key=YOUR_API_KEY

2. 视频模型列表

请求

GET /api/models?modality=video

响应示例

{
  "models": [
    {
      "id": "tiaotiao:video:t2v",
      "name": "视频生成",
      "modality": "video",
      "task_type": "text_to_video",
      "supported_aspect_ratios": ["9:16", "16:9", "1:1", "4:3", "3:4", "21:9"],
      "supported_durations": [5, 10, 15],
      "audio": true
    },
    {
      "id": "tiaotiao:video:i2v",
      "name": "图生视频",
      "modality": "video",
      "task_type": "image_to_video",
      "supported_aspect_ratios": ["9:16", "16:9", "1:1", "4:3", "3:4", "21:9"],
      "supported_durations": [5, 10, 15],
      "audio": true
    }
  ]
}

说明：视频固定带音频，客户端不需要传递音频开关字段。

3. 提交文生视频任务

请求

POST /v1/videos/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body

{
  "model": "tiaotiao:video:t2v",
  "prompt": "一只橘猫在雨夜霓虹街道上奔跑，电影感镜头",
  "duration": 10,
  "ratio": "9:16"
}

字段

字段 类型 必填 说明
model string 否 视频模型 ID；默认文生视频
prompt string 是 视频提示词
duration integer 否 秒数，支持 5、10、15；默认 15
ratio string 否 比例，支持 9:16、16:9、1:1、4:3、3:4、21:9；默认 9:16

响应示例

{
  "task_id": "24368c66b7b1447a9644f52265853742",
  "status": "queued"
}

4. 提交图生视频任务

请求

POST /v1/videos/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body：base64 图片

{
  "model": "tiaotiao:video:i2v",
  "prompt": "让画面中的人物向镜头微笑并挥手，镜头缓慢推进",
  "duration": 10,
  "ratio": "9:16",
  "images": [
    {
      "name": "first-frame.jpg",
      "mime": "image/jpeg",
      "data_b64": "BASE64_IMAGE_DATA"
    }
  ]
}

Body：已上传文件路径

{
  "model": "tiaotiao:video:i2v",
  "prompt": "让图片中的场景动起来，电影感光影",
  "duration": 10,
  "ratio": "16:9",
  "input_files": ["uploads/OBJECT_KEY"]
}

说明：

5. 上传图片文件

网页端可使用预签名上传流程。

5.1 获取上传地址

POST /api/upload/presign-object
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body：

{
  "filename": "first-frame.jpg",
  "content_type": "image/jpeg"
}

响应：

{
  "upload_url": "/api/nexus-upload/UPLOAD_TOKEN",
  "object_key": "uploads/UPLOAD_TOKEN",
  "headers": {
    "Content-Type": "image/jpeg",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  "filename": "first-frame.jpg"
}

5.2 上传文件

PUT /api/nexus-upload/UPLOAD_TOKEN
Authorization: Bearer YOUR_API_KEY
Content-Type: image/jpeg

Body 为图片二进制。

5.3 确认上传

POST /api/upload/confirm-object
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body：

{
  "object_key": "uploads/UPLOAD_TOKEN"
}

响应：

{
  "object_key": "uploads/UPLOAD_TOKEN",
  "path": "uploads/UPLOAD_TOKEN",
  "url": "/uploads/UPLOAD_TOKEN",
  "public_url": "/uploads/UPLOAD_TOKEN"
}

6. 查询任务状态

请求

GET /v1/tasks/{task_id}
Authorization: Bearer YOUR_API_KEY

响应：排队中

{
  "task_id": "24368c66b7b1447a9644f52265853742",
  "type": "video",
  "status": "queued",
  "model": "tiaotiao:video:t2v",
  "ratio": "9:16",
  "duration": 10,
  "progress": "正在生成",
  "result_urls": [],
  "video_url": null,
  "download_url": null,
  "error": null
}

响应：生成中

{
  "task_id": "24368c66b7b1447a9644f52265853742",
  "type": "video",
  "status": "running",
  "model": "tiaotiao:video:t2v",
  "ratio": "9:16",
  "duration": 10,
  "progress": "正在生成",
  "result_urls": [],
  "video_url": null,
  "download_url": null,
  "error": null
}

响应：成功

{
  "task_id": "24368c66b7b1447a9644f52265853742",
  "type": "video",
  "status": "success",
  "model": "tiaotiao:video:t2v",
  "ratio": "9:16",
  "duration": 10,
  "progress": "生成完成",
  "result_urls": [
    "/v1/tasks/24368c66b7b1447a9644f52265853742/video"
  ],
  "video_url": "/v1/tasks/24368c66b7b1447a9644f52265853742/video",
  "download_url": "/v1/tasks/24368c66b7b1447a9644f52265853742/video",
  "error": null
}

响应：失败

{
  "task_id": "24368c66b7b1447a9644f52265853742",
  "type": "video",
  "status": "failed",
  "model": "tiaotiao:video:t2v",
  "ratio": "9:16",
  "duration": 10,
  "progress": "生成失败",
  "result_urls": [],
  "video_url": null,
  "download_url": null,
  "error": "生成失败，请稍后重试"
}

状态枚举：

状态 说明
queued 已提交，等待处理
running 正在生成
success 已完成
failed 失败

7. 下载/播放视频

请求

GET /v1/tasks/{task_id}/video
Authorization: Bearer YOUR_API_KEY

成功时返回 video/mp4 文件流。

也可直接访问查询任务返回的 video_url：

https://api.tiaotiao.shop/v1/tasks/{task_id}/video

注意：该地址是网关本机视频地址。

8. 兼容网页任务接口

登录

POST /api/auth/login
Content-Type: application/x-www-form-urlencoded

Body：

username=USERNAME&password=API_KEY

响应：

{
  "access_token": "API_KEY",
  "token_type": "bearer",
  "user": {
    "id": "USER_ID",
    "username": "USERNAME",
    "display_name": "USERNAME",
    "credits": 1000,
    "balance_points": 1000,
    "is_admin": false
  }
}

创建网页任务

POST /api/tasks/
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

文生视频：

{
  "task_type": "text_to_video",
  "global_prompt": "城市夜景延时摄影，霓虹灯闪烁",
  "config_json": {
    "model": "tiaotiao:video:t2v",
    "aspect_ratio": "9:16",
    "seconds": 10
  },
  "tasks": [
    {"prompt": "城市夜景延时摄影，霓虹灯闪烁"}
  ]
}

图生视频：

{
  "task_type": "image_to_video",
  "global_prompt": "图片中的人物自然转头，背景微风摆动",
  "config_json": {
    "model": "tiaotiao:video:i2v",
    "aspect_ratio": "9:16",
    "seconds": 10
  },
  "tasks": [
    {"input_files": ["uploads/OBJECT_KEY"]}
  ]
}

响应：

{
  "id": "TASK_ID",
  "title": "文生视频 城市夜景延时摄影",
  "task_type": "text_to_video",
  "status": "queued",
  "total_count": 1,
  "completed_count": 0,
  "failed_count": 0,
  "progress_message": "正在生成",
  "tasks": [
    {
      "id": "TASK_ID",
      "status": "queued",
      "output_file": null,
      "source_url": null
    }
  ]
}

任务列表

GET /api/tasks/?limit=100
Authorization: Bearer YOUR_API_KEY

网页视频文件

GET /v1/tasks/{task_id}/video
Authorization: Bearer YOUR_API_KEY

成功时返回 video/mp4 文件流。

9. 常见错误

HTTP 状态 说明
400 请求参数错误
401 API Key 无效或缺失
402 当前用户余额不足
404 任务或文件不存在
409 任务生成中，暂不可删除
429 当前队列繁忙，请稍后重试
500 服务端处理异常

错误响应示例：

{
  "detail": "生成队列已满，请稍后重试"
}

10. 调用示例

cURL 提交文生视频

curl -X POST "https://api.tiaotiao.shop/v1/videos/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"tiaotiao:video:t2v",
    "prompt":"一只橘猫在雨夜霓虹街道上奔跑，电影感镜头",
    "duration":10,
    "ratio":"9:16"
  }'

cURL 查询任务

curl "https://api.tiaotiao.shop/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

cURL 下载视频

curl -L "https://api.tiaotiao.shop/v1/tasks/TASK_ID/video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o result.mp4