开发者文档

1. API 基础信息

所有接口均通过 HTTPS 提供服务，请求与响应主体默认使用 JSON。视频处理任务采用异步队列模型，客户端提交任务后通过任务 ID 查询进度，或通过 Webhook 接收最终结果。

Base URL:
https://api.tutuai.com

Content-Type:
application/json; charset=utf-8

API Version:
v1

2. 认证机制

API 请求需要携带项目级访问令牌。服务端会校验 Bearer Token、项目标识、请求时间戳和签名字段。未登录、令牌失效、权限不足或项目未开通时，会返回统一认证错误。

Authorization: Bearer <access_token>
X-Tutu-Project: <project_id>
X-Tutu-Timestamp: 1770000000
X-Tutu-Signature: HMAC-SHA256(method + path + timestamp + body)

3. 幂等请求

创建视频任务、字幕任务、模板任务等写入操作建议携带 Idempotency-Key，避免网络重试导致重复创建任务。

Idempotency-Key: 6f4e3f7a-3f8c-4f98-8a42-9f761f1a2c73

4. 创建 AI 剪辑任务

POST /api/v1/video/jobs
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "title": "新品发布会 30 秒短视频",
  "input_url": "https://cdn.example.com/input.mp4",
  "workflow": "ai_editing",
  "modules": [
    "scene_detection",
    "speech_to_text",
    "highlight_scoring",
    "portrait_enhancement",
    "auto_export"
  ],
  "export": {
    "preset": "douyin_1080x1920",
    "format": "mp4",
    "fps": 30
  },
  "webhook_url": "https://example.com/webhooks/tutucloud"
}

5. 查询任务状态

GET /api/v1/video/jobs/{job_id}
Authorization: Bearer <access_token>

6. Webhook 回调

任务完成、失败、取消、素材不可访问、导出完成等事件会通过 Webhook 推送到业务系统。回调请求会携带事件 ID、签名、时间戳和任务状态。

POST /your-webhook-url
X-Tutu-Event: video.job.completed
X-Tutu-Delivery: evt_2xN8z9Qp
X-Tutu-Timestamp: 1770000000
X-Tutu-Signature: sha256=...

{
  "event": "video.job.completed",
  "job_id": "job_8f3a91c2",
  "status": "completed",
  "output_url": "https://cdn.example.com/output.mp4"
}

7. 分页与筛选

GET /api/v1/video/jobs?status=processing&limit=20&cursor=eyJpZCI6...

8. 错误结构

{
  "error": {
    "code": "unauthenticated",
    "message": "当前请求未登录或登录状态已失效，请登录 tutu TUTUCLOUD Console 后重试。",
    "type": "authentication_error",
    "request_id": "req_xxxxxxxxxxxxxx",
    "documentation_url": "/docs"
  }
}

9. 常见错误码

10. 可用 API