统一格式接口介绍

一句话说明：本平台为视频类模型提供一套统一接口格式，提交任务与查询结果都走固定路径，换模型通常只需改 model 字段，便于批量集成。

请求体的场景判定规则：

请求体中出现 images 字段 → 按「图片生成视频」处理；
请求体中出现 videos 字段 → 按「视频生成视频」处理；
两者都没有 → 按纯文生视频处理。

口径修正：源文档此处把字段名误写为 imagese，实际字段为 images；参数名一律以本节「接口定义」为准。

任务状态

状态值	含义
NOT_START	未开始
SUBMITTED	已提交任务
QUEUED	队列中
IN_PROGRESS	正在执行
SUCCESS	执行完成
FAILURE	失败

接口定义

1. 提交

scope 取值：images / videos / audio

Post: /v2/{scope}/generations

例如：Post: /v2/videos/generations

请求头：

Authorization: Bearer <API-Key>

入参：

text

{
    "prompt": "",        // 必填
    "model": "",         // 必填
    "duration": 5,
    "aspect_ratio": "16:9",
    "size": "",
    "resolution": "720P",   // 可选档位以模型广场展示为准
    "images": [""],         // URL 或 base64
    "videos": [""],         // 仅支持 URL
    "watermark": false
    ...
}

text

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

2. 获取

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

请求头：

Authorization: Bearer <API-Key>

text

{
    "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": ["", ""]
    }
}

data 内除 output / outputs 外还可能有其他字段，按具体模型返回为准。

使用示例

下面以视频生成为例走一遍完整流程。示例中的模型名请以「模型广场」在售列表为准。

1) 准备

先在控制台创建令牌，后续所有请求都带上：

Authorization: Bearer <API-Key>

2) 提交任务

POST /v2/{scope}/generations

传 images 视为图片生成视频，传 videos 视为视频生成视频，都不传即纯文生视频。

text

curl -X POST "https://api.allyang.cn/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 分钟）可按超时处理。

text

curl -X GET "https://api.allyang.cn/v2/videos/generations/{task_id}" \
  -H "Authorization: Bearer <API-Key>"

text

{
    "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": "<平台返回的视频地址>"
    },
    "search_item": ""
}

4) 取回并持久化结果

从 data.output 或 data.outputs 读取地址后，请尽快转存到你自己的对象存储：这类地址通常带有效期。

统一格式接口介绍

任务状态

接口定义

1. 提交

2. 获取

使用示例

1) 准备

2) 提交任务

3) 轮询查询进度

4) 取回并持久化结果

相关页面