# 统一格式接口介绍

**实现统一的接口格式接入，方便用户集成**

接口会根据传参里是否有imagese字段判断为图片生成视频， videos字段判断为视频生成视频

### 任务状态

NOT\_START ： 未开始
SUBMITTED : 已提交任务
QUEUED ： 队列中
IN\_PROGRESS ： 正在执行
SUCCESS ： 执行完成
FAILURE ： 失败

### 接口定义

#### 1. 提交

> scope: images\videos\audio

`Post: /v2/{scope}/generations`
例如： `Post: /v2/videos/generations`

header:
`Authorization: Bearer <API-Key>`

input:

```
{
"prompt": "", // 必须
"model": "", // 必须
"duration": 5,
"aspect_ratio": "16:9",
"size": "",
"resolution": "780P",
"images": [""], // url or b64
"videos": [""], // only url
"watermark": false
......
}
```

output:

```
{
"task_id": "f186f65a-8657-4e83-b0e3-67facf1b2576",
}
```

#### 2. 获取

`Get: /v2/{scope}/generations/:task_id`

header:
`Authorization: Bearer <API-Key>`

output:

```
{
"task_id": "f4a94d75-087b-4bb1-bd45-53ba293faf96",
"status": "SUCCESS",
"fail_reason": "",
"submit_time": 1716192124,
"start_time": 1716192124,
"finish_time": 1716192124,
"progress": "100%",
"data": {
"output": "",
"outputs": ["",""],
other...
}
}
```

### 使用示例

以 Veo 视频生成为例

1. 准备

获取 API-Key，为所有请求加
`Authorization: Bearer <API-Key>`

2. 提交任务（POST /v2/{scope}/generations）
存在 images → 视为“图片生成视频”；存在 videos → 视为“视频生成视频”；都无 → 纯文生视频

```
curl -X POST "/v2/videos/generations"
-H "Authorization: Bearer <API-Key>"
-H "Content-Type: application/json"
-d '{
"prompt": "A cat surfing in sunset, cinematic",
"model": "veo3"
}'
```

返回

`{ "task_id": "f186f65a-8657-4e83-b0e3-67facf1b2576" }`

3. 轮询查询进度

客户端每 2s → 4s → 8s 指数退避调用
`GET /v2/{scope}/generations/:task_id`

当 status为 SUCCESS / FAILURE 即停止；
超过自定义超时（如 30 分钟）提示超时

```
curl -X GET "/v2/videos/generations/{task_id}"
-H "Authorization: Bearer <API-Key>"
```

返回

```
{
"task_id": "veo3:1756693796-YQVHH4A3Lg",
"platform": "google",
"action": "google-videos",
"status": "SUCCESS",
"fail_reason": "",
"submit_time": 1756693797,
"start_time": 1756693808,
"finish_time": 1756693898,
"progress": "100%",
"data": {
"output": "https://filesystem.site/cdn/20250901/018eg2SgUpHMT6EEuQbfeRLWeUhE75.mp4"
},
"search_item": ""
}
```

4. 取回并持久化结果

读取 data.output 或 data.outputs