易尚云视频生成 API

强大、灵活的视频生成服务接口文档

RESTful API JSON 格式 异步处理

概述

易尚云视频生成 API 提供了强大的视频生成服务，支持文本到视频、图像到视频等多种生成模式。 本 API 采用 RESTful 架构设计，使用 JSON 格式进行数据交换，支持异步任务处理。

高性能

采用分布式架构，支持大规模并发请求

安全可靠

完整的认证授权机制，保障数据安全

易于集成

标准化的接口设计，快速集成到现有系统

认证方式

API 使用 Bearer Token 认证方式。您需要在请求头中包含有效的认证令牌。 

Authorization: Bearer sk-your-api-key-here

安全提示

  • • 请妥善保管您的 API 密钥，不要在客户端代码中暴露
  • • 建议定期轮换 API 密钥以提高安全性
  • • 为不同的应用场景使用不同的 API 密钥

接口列表

POST /v1/videos

提交视频生成任务

GET /v1/videos/:task_id

查询视频生成任务状态和结果

POST /v1/videos

POST /v1/videos

提交视频生成任务，支持文本到视频和图像到视频两种模式。

请求参数

参数名 类型 必填 说明 示例
model string 是 视频生成模型名称 sora-2,sora-2-hd,sora-2-pro,veo3,veo3-pro,veo3.1,veo3.1-pro
prompt string 是 视频描述文本 A cat playing piano
seconds string 否 时长 10,15
size string 否 视频宽高比 720x1280,1280x720
seconds file 否 参考附件

请求示例

curl -X POST "https://api.example.com/v1/videos" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A cat playing piano in the garden",
    "size": "720x1280",
    "seconds": "5",
    "input_reference": ["https://example.com/image.jpg"]
  }'

响应示例

200 OK 任务提交成功 
{
  "task_id": "task_123456789",
  "status": "queued",
  "message": "视频生成任务已提交，正在处理中"
}

GET /v1/videos/:task_id

GET /v1/videos/:task_id

根据任务ID查询视频生成任务的状态和结果。

路径参数

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

请求示例

curl -X GET "https://api.example.com/v1/videos/task_123456789" \
  -H "Authorization: Bearer sk-your-api-key"

响应示例

200 OK 任务处理中 
{
  "task_id": "task_123456789",
  "status": "processing",
  "progress": 45,
  "message": "视频生成中，已完成45%"
}
200 OK 任务完成 
{
  "task_id": "task_123456789",
  "status": "completed",
  "progress": 100,
  "video_url": "https://cdn.example.com/videos/task_123456789.mp4",
  "thumbnail_url": "https://cdn.example.com/thumbnails/task_123456789.jpg",
  "seconds": 5.2,
  "width": 1920,
  "height": 1080,
  "file_size": 15728640,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:35:12Z"
}

错误码

API 使用标准的 HTTP 状态码，并在响应体中提供详细的错误信息。

400 Bad Request

请求参数错误或格式不正确

{
  "error": {
    "message": "prompt field is required",
    "type": "invalid_request_error",
    "code": "missing_parameter"
  }
}
401 Unauthorized

认证失败或API密钥无效

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
403 Forbidden

权限不足或配额已用完

{
  "error": {
    "message": "Insufficient quota",
    "type": "permission_error",
    "code": "insufficient_quota"
  }
}
404 Not Found

任务不存在或已过期

{
  "error": {
    "message": "Task not found",
    "type": "not_found_error",
    "code": "task_not_found"
  }
}
429 Too Many Requests

请求频率超限

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}
500 Internal Server Error

服务器内部错误

{
  "error": {
    "message": "Internal server error",
    "type": "server_error",
    "code": "internal_error"
  }
}