热门模型使用快速接入

这份文档适合已经拿到 API Key、准备直接写代码接入的开发者。本文聚焦 3 个常用模型：

mart-image-2：异步图像生成
veo3.1_fast：异步视频生成
doubao-seedance-2-0：异步视频生成

这 3 个模型都使用兼容 OpenAI 的统一接口风格，但图像任务和视频任务的提交路径、查询路径、结果字段并不完全相同。

第一步：准备基础信息

在开始之前，你需要准备 3 项内容：

API Key
Base URL
模型名

Base URL

统一使用：

https://xcompute.us

Authorization 请求头

所有请求都需要带上：

Authorization: Bearer YOUR_API_KEY

Content-Type

除图片上传接口外，本文示例均使用：

Content-Type: application/json

第二步：理解异步任务查询规则

这 3 个模型都不是同步返回最终资源，而是先返回 task_id，然后再轮询任务状态。规则如下：

图像任务：查询 GET /v1/tasks/{task_id}
视频任务：查询 GET /v1/videos/{task_id}

不要混用查询路径。图像任务去查 /v1/videos/{task_id}，或者视频任务去查 /v1/tasks/{task_id}，都会导致结果异常或直接报错。

模型一：mart-image-2

mart-image-2 是异步图像生成模型。提交任务后，你需要通过 /v1/tasks/{task_id} 查询结果。

1. 提交任务

接口：

POST /v1/images/generations

示例：

curl --request POST \
  --url https://xcompute.us/v1/images/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "mart-image-2",
    "prompt": "一只橘猫坐在窗台上看夕阳，水彩画风格",
    "n": 1,
    "size": "16:9",
    "resolution": "2k"
  }'

2. 请求参数说明

参数	类型	是否必填	说明
`model`	string	是	固定填写 `mart-image-2`
`prompt`	string	是	图像描述文本
`n`	integer	否	生成张数。建议填 `1`
`size`	string	否	图片比例，例如 `1:1`、`16:9`、`9:16`
`resolution`	string	否	输出档位，常见值：`1k`、`2k`、`4k`

3. 提交成功响应

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_xxx"
    }
  ]
}

你需要从以下字段中取出任务 ID：

data[0].task_id

4. 查询任务状态

接口：

GET /v1/tasks/{task_id}

示例：

curl --request GET \
  --url https://xcompute.us/v1/tasks/YOUR_TASK_ID \
  --header 'Authorization: Bearer YOUR_API_KEY'

5. 查询响应关键字段

当任务成功后，结果通常位于：

data.result.images[0].url[0]

常见字段：

字段路径	含义
`data.status`	任务状态
`data.progress`	任务进度
`data.result.images[0].url[0]`	最终图片地址

模型二：veo3.1_fast

veo3.1_fast 是异步视频生成模型。提交任务后，你需要通过 /v1/videos/{task_id} 查询结果。

1. 提交任务

接口：

POST /v1/videos/generations

示例：

curl --request POST \
  --url https://xcompute.us/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "veo3.1_fast",
    "prompt": "海豚在碧蓝海洋中跳跃",
    "duration": 8,
    "aspect_ratio": "16:9",
    "image_urls": [
      "https://example.com/reference-image.jpg"
    ]
  }'

2. 请求参数说明

参数	类型	是否必填	说明
`model`	string	是	固定填写 `veo3.1_fast`
`prompt`	string	是	视频描述文本
`duration`	integer	否	视频时长。常见值 `8`
`aspect_ratio`	string	否	宽高比，例如 `16:9`、`9:16`
`image_urls`	`array<string>`	否	图生视频参考图 URL 数组

3. 提交成功响应

{
  "id": "task_upstream_id",
  "task_id": "task_public_id",
  "object": "video",
  "model": "veo3.1_fast",
  "status": "queued",
  "progress": 0
}

你需要用以下字段进行查询：

task_id

4. 查询任务状态

接口：

GET /v1/videos/{task_id}

示例：

curl --request GET \
  --url https://xcompute.us/v1/videos/YOUR_TASK_ID \
  --header 'Authorization: Bearer YOUR_API_KEY'

5. 查询响应关键字段

不同渠道返回的最终视频字段可能有轻微差异，常见可用字段如下：

video_url
output_url
url

如果你在平台内部做渠道配置，建议优先取：

video_url

如果某个渠道返回的是别名字段，也可以兼容读取 output_url 或 url。

模型三：doubao-seedance-2-0

doubao-seedance-2-0 是异步视频生成模型，也通过 /v1/videos/{task_id} 查询结果。

1. 提交任务

接口：

POST /v1/videos/generations

示例：

curl --request POST \
  --url https://xcompute.us/v1/videos/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "doubao-seedance-2-0",
    "prompt": "小猫对着镜头打哈欠",
    "resolution": "720p",
    "size": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

2. 请求参数说明

参数	类型	是否必填	说明
`model`	string	是	固定填写 `doubao-seedance-2-0`
`prompt`	string	是	视频描述文本
`resolution`	string	否	分辨率，例如 `480p`、`720p`、`1080p`
`size`	string	否	宽高比，例如 `16:9`、`9:16`、`1:1`
`duration`	integer	否	视频时长，常见值 `5`
`generate_audio`	boolean	否	是否生成音频

3. 提交成功响应

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_xxx"
    }
  ]
}

你需要从以下字段中取出任务 ID：

data[0].task_id

4. 查询任务状态

接口：

GET /v1/videos/{task_id}

示例：

curl --request GET \
  --url https://xcompute.us/v1/videos/YOUR_TASK_ID \
  --header 'Authorization: Bearer YOUR_API_KEY'

5. 查询响应关键字段

常见字段：

字段路径	含义
`status`	任务状态
`progress`	任务进度
`video_url`	视频地址

如果你收到 AccountOverdueError，通常不是请求体参数错误，而是上游视频渠道账户欠费或不可用，需要切换渠道或联系上游处理。

第三步：推荐轮询策略

你可以按下面的方式轮询异步任务：

提交成功后，先等待 5 到 10 秒
再开始查询任务状态
轮询间隔建议 3 到 5 秒
当状态变成 completed 时，读取结果 URL

如果是图像任务，建议优先读取 data.result.images[0].url[0]。如果是视频任务，建议优先读取 video_url。

第四步：常见错误与处理方式

1. `model_not_found`

说明当前分组下没有可用渠道承接这个模型。排查方向：

模型名是否拼写正确
当前 API Key 是否有权限访问这个模型
对应渠道是否启用

2. `AccountOverdueError`

说明上游视频渠道账户欠费，不是调用方 JSON 参数写错。排查方向：

更换上游渠道
联系上游处理余额问题

3. `Invalid URL`

通常说明你把图像任务和视频任务的查询路径混用了。请重新确认：

图像任务查 /v1/tasks/{task_id}
视频任务查 /v1/videos/{task_id}

Documentation Index

​第一步：准备基础信息

​Base URL

​Authorization 请求头

​Content-Type

​第二步：理解异步任务查询规则

​模型一：mart-image-2

​1. 提交任务

​2. 请求参数说明

​3. 提交成功响应

​4. 查询任务状态

​5. 查询响应关键字段

​模型二：veo3.1_fast

​1. 提交任务

​2. 请求参数说明

​3. 提交成功响应

​4. 查询任务状态

​5. 查询响应关键字段

​模型三：doubao-seedance-2-0

​1. 提交任务

​2. 请求参数说明

​3. 提交成功响应

​4. 查询任务状态

​5. 查询响应关键字段

​第三步：推荐轮询策略

​第四步：常见错误与处理方式

​1. model_not_found

​2. AccountOverdueError

​3. Invalid URL

​推荐你先从哪个模型开始

第一步：准备基础信息

Base URL

Authorization 请求头

Content-Type

第二步：理解异步任务查询规则

模型一：mart-image-2

1. 提交任务

2. 请求参数说明

3. 提交成功响应

4. 查询任务状态

5. 查询响应关键字段

模型二：veo3.1_fast

1. 提交任务

2. 请求参数说明

3. 提交成功响应

4. 查询任务状态

5. 查询响应关键字段

模型三：doubao-seedance-2-0

1. 提交任务

2. 请求参数说明

3. 提交成功响应

4. 查询任务状态

5. 查询响应关键字段

第三步：推荐轮询策略

第四步：常见错误与处理方式

1. `model_not_found`

2. `AccountOverdueError`

3. `Invalid URL`

推荐你先从哪个模型开始