AI Video API 文档

基本信息

Base URL: https://vibegen.art/api/v1

认证方式: Bearer Token (API Key)

所有请求都需要在 Header 中携带 API Key：

Authorization: Bearer YOUR_API_KEY

---

1. 创建视频生成任务

端点

POST /api/v1/generations

请求头

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

请求参数

参数名	类型	必填	说明	示例
model	string	是	模型名称	"seedance 2.0"
prompt	string	是	视频描述文本	"一座未来城市，飞行汽车在日落时分穿梭"
image_urls	string[]	否	参考图片 URL 数组（图生视频时必填）	["https://example.com/image.jpg"]
duration	number	否	视频时长（秒），默认 5	5 或 10
aspect_ratio	string	否	宽高比，默认 "16:9"	"16:9", "9:16", "1:1", "21:9", "4:3", "3:4", "9:21", "adaptive", "keep_ratio"
resolution	string	否	分辨率，默认 "480p"	"480p", "720p", "1080p"
generate_audio	boolean	否	是否生成有声视频，默认 false	true 或 false
callback_url	string	否	任务完成后的回调 URL	"https://vibegen.art/webhook"

请求示例

文生视频（无声）

curl -X POST https://vibegen.art/api/v1/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-video-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "seedance 2.0",
    "prompt": "写实风格，晴朗的蓝天之下，一大片白色的雏菊花田，镜头逐渐拉近",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

文生视频（有声）

curl -X POST https://vibegen.art/api/v1/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-video-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "seedance 2.0",
    "prompt": "女孩抱着狐狸，可以听到风声和鸟鸣",
    "duration": 5,
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

图生视频

curl -X POST https://vibegen.art/api/v1/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-video-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "seedance 2.0",
    "prompt": "女孩睁开眼，温柔地看向镜头，头发被风吹动",
    "image_urls": ["https://example.com/girl-with-fox.png"],
    "duration": 5,
    "aspect_ratio": "adaptive",
    "generate_audio": true
  }'

响应示例

成功响应 (201 Created)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "model": "seedance 2.0",
    "task_type": "text_to_video",
    "created_at": "2025-03-10T10:00:00Z"
  }
}

错误响应 (400 Bad Request)

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Missing required parameters: model, prompt"
  }
}

错误响应 (401 Unauthorized)

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or missing API key"
  }
}

错误响应 (402 Payment Required)

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits. Required: 100, Available: 50"
  }
}

---

2. 查询任务状态

端点

GET /api/v1/tasks/{task_id}

请求头

Authorization: Bearer YOUR_API_KEY

路径参数

参数名	类型	必填	说明
task_id	string	是	任务 ID

请求示例

curl -X GET https://vibegen.art/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk-video-xxxxxxxxxxxxxxxx"

响应示例

任务进行中 (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "model": "seedance 2.0",
    "task_type": "text_to_video",
    "prompt": "一座未来城市，飞行汽车在日落时分穿梭",
    "video_url": null,
    "created_at": "2025-03-10T10:00:00Z",
    "completed_at": null,
    "error": null
  }
}

任务完成 (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "model": "seedance 2.0",
    "task_type": "text_to_video",
    "prompt": "一座未来城市，飞行汽车在日落时分穿梭",
    "video_url": "https://cdn.example.com/videos/abc123.mp4",
    "created_at": "2025-03-10T10:00:00Z",
    "completed_at": "2025-03-10T10:02:30Z",
    "error": null
  }
}

任务失败 (200 OK)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "model": "seedance 2.0",
    "task_type": "text_to_video",
    "prompt": "一座未来城市，飞行汽车在日落时分穿梭",
    "video_url": null,
    "created_at": "2025-03-10T10:00:00Z",
    "completed_at": null,
    "error": "Content policy violation"
  }
}

任务不存在 (404 Not Found)

{
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task not found"
  }
}

---

3. 获取任务列表

端点

GET /api/v1/tasks

请求头

Authorization: Bearer YOUR_API_KEY

查询参数

参数名	类型	必填	说明	默认值
status	string	否	按状态筛选：pending, processing, completed, failed	全部
limit	number	否	每页数量	20
offset	number	否	偏移量	0

请求示例

curl -X GET "https://vibegen.art/api/v1/tasks?status=completed&limit=10" \
  -H "Authorization: Bearer sk-video-xxxxxxxxxxxxxxxx"

响应示例 (200 OK)

{
  "success": true,
  "data": {
    "tasks": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "completed",
        "model": "seedance 2.0",
        "task_type": "text_to_video",
        "prompt": "一座未来城市",
        "video_url": "https://cdn.example.com/videos/abc123.mp4",
        "created_at": "2025-03-10T10:00:00Z",
        "completed_at": "2025-03-10T10:02:30Z",
        "error": null
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 1,
      "total_pages": 1
    }
  }
}

---

4. 回调通知

如果在创建任务时提供了 callback_url，任务完成或失败时会向该 URL 发送 POST 请求。

回调请求

请求头

Content-Type: application/json

请求体（任务完成）

{
  "event": "task.completed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "video_url": "https://cdn.example.com/videos/abc123.mp4",
  "created_at": "2025-03-10T10:00:00Z",
  "completed_at": "2025-03-10T10:02:30Z"
}

请求体（任务失败）

{
  "event": "task.failed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error_message": "Content policy violation",
  "created_at": "2025-03-10T10:00:00Z",
  "failed_at": "2025-03-10T10:00:15Z"
}

---

5. 状态说明

状态	说明
pending	任务已创建，等待处理
processing	任务正在生成中
completed	任务已完成，视频生成成功
failed	任务失败

---

6. 错误码

错误码	HTTP 状态码	说明
INVALID_API_KEY	401	API Key 无效或缺失
INVALID_PARAMETER	400	请求参数错误
INSUFFICIENT_CREDITS	402	积分不足
TASK_NOT_FOUND	404	任务不存在
RATE_LIMIT_EXCEEDED	429	请求频率超限
PROVIDER_ERROR	502	第三方服务错误
INTERNAL_ERROR	500	服务器内部错误

---

7. 费用说明

Seedance 2.0 的积分收费标准如下：

分辨率	画面比例	视频时长	积分收费（有声）	无声积分收费
480p	所有支持的	5s	20	15
720p	所有支持的	5s	43	30
1080p	所有支持的	5s	90	50
480p	所有支持的	10s	40	25
720p	所有支持的	10s	86	45
1080p	所有支持的	10s	180	100

注意：

• 有声视频需设置 generate_audio: true
• 图生视频费用与文生视频相同
• 所有画面比例（aspect_ratio）的费用相同

---

8. 限制说明

速率限制

• 每个 API Key 每分钟最多创建 1000 个任务
• 每个 API Key 每分钟最多查询 1000 次

内容限制

• prompt 最大长度：2000 字符
• 支持的视频时长：5 秒或 10 秒
• 支持的宽高比：16:9, 9:16, 1:1, 21:9, 4:3, 3:4, 9:21, adaptive, keep_ratio
• 支持的分辨率：480p, 720p, 1080p

超时时间

• 视频生成任务超时时间：10 分钟
• 超时后任务状态将变为 failed

---

9. SDK 示例

JavaScript/Node.js

const axios = require('axios');

const API_KEY = 'sk-video-xxxxxxxxxxxxxxxx';
const BASE_URL = 'https://vibegen.art/api/v1';

// 创建视频生成任务
async function createVideoTask() {
  const response = await axios.post(`${BASE_URL}/generations`, {
    model: 'seedance 2.0',
    prompt: '一座未来城市，飞行汽车在日落时分穿梭',
    duration: 5,
    aspect_ratio: '16:9',
    resolution: '720p'
  }, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  
  return response.data.data.id;
}

// 查询任务状态
async function getTaskStatus(taskId) {
  const response = await axios.get(`${BASE_URL}/tasks/${taskId}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  
  return response.data.data;
}

// 轮询等待任务完成
async function waitForCompletion(taskId) {
  while (true) {
    const task = await getTaskStatus(taskId);
    
    if (task.status === 'completed') {
      console.log('视频生成完成:', task.video_url);
      return task;
    } else if (task.status === 'failed') {
      console.error('视频生成失败:', task.error_message);
      throw new Error(task.error_message);
    }
    
    console.log('任务进行中...');
    await new Promise(resolve => setTimeout(resolve, 5000)); // 等待 5 秒
  }
}

// 使用示例
(async () => {
  try {
    const taskId = await createVideoTask();
    console.log('任务已创建:', taskId);
    
    const result = await waitForCompletion(taskId);
    console.log('最终结果:', result);
  } catch (error) {
    console.error('错误:', error.message);
  }
})();

Python

import requests
import time

API_KEY = 'sk-video-xxxxxxxxxxxxxxxx'
BASE_URL = 'https://vibegen.art/api/v1'

def create_video_task():
    """创建视频生成任务"""
    response = requests.post(
        f'{BASE_URL}/generations',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json'
        },
        json={
            'model': 'seedance 2.0',
            'prompt': '一座未来城市，飞行汽车在日落时分穿梭',
            'duration': 5,
            'aspect_ratio': '16:9',
            'resolution': '720p'
        }
    )
    response.raise_for_status()
    data = response.json()
    return data['data']['id']

def get_task_status(task_id):
    """查询任务状态"""
    response = requests.get(
        f'{BASE_URL}/tasks/{task_id}',
        headers={'Authorization': f'Bearer {API_KEY}'}
    )
    response.raise_for_status()
    data = response.json()
    return data['data']

def wait_for_completion(task_id):
    """轮询等待任务完成"""
    while True:
        task = get_task_status(task_id)
        
        if task['status'] == 'completed':
            print(f"视频生成完成: {task['video_url']}")
            return task
        elif task['status'] == 'failed':
            raise Exception(f"视频生成失败: {task.get('error_message')}")
        
        print('任务进行中...')
        time.sleep(5)

# 使用示例
if __name__ == '__main__':
    try:
        task_id = create_video_task()
        print(f'任务已创建: {task_id}')
        
        result = wait_for_completion(task_id)
        print(f'最终结果: {result}')
    except Exception as e:
        print(f'错误: {e}')

---

10. 最佳实践

1. 错误处理

• 始终检查 HTTP 状态码
• 处理所有可能的错误响应
• 实现重试机制（建议指数退避）

2. 轮询策略

• 建议每 5-10 秒轮询一次任务状态
• 设置最大轮询次数或超时时间
• 使用回调 URL 代替轮询（推荐）

3. 性能优化

• 批量创建任务时注意速率限制
• 缓存已完成任务的结果
• 使用 CDN 加速视频访问

4. 安全建议

• 妥善保管 API Key，不要提交到代码仓库
• 使用环境变量存储 API Key
• 定期轮换 API Key
• 验证回调请求的签名

---

11. 常见问题

Q: 视频生成需要多长时间？

A: 通常 30-120 秒，具体取决于模型、分辨率和服务器负载。

Q: 生成的视频保存多久？

A: 生成的视频和返回的视频 URL 有效期为 24 小时，请在此期间内及时下载保存到您本地。24 小时后视频文件将被永久删除。

Q: 如何获取 API Key？

A: 登录控制台，在 API 密钥页面创建新密钥。

Q: 积分如何充值？

A: 在控制台的账单页面选择充值套餐。

Q: 支持哪些语言的 prompt？

A: 支持中文和英文，建议使用详细的描述以获得更好的效果。

Q: 可以生成多长的视频？

A: 目前支持 5 秒和 10 秒两种时长。

---

12. 联系支持

• 技术文档：https://vibegen.art/docs
• 邮件支持：[email protected]
• 工单系统：https://vibegen.art

---

版本: v1.0
最后更新: 2025-03-10