主题
OpenAI 兼容接口
Base URL:https://api.video.aistarslab.com/openai,下方路径均相对于此地址。
New API 等兼容平台的 API 地址填写上述地址;若客户端要求地址包含 /v1,则填写 https://api.video.aistarslab.com/openai/v1。
兼容范围
提供模型列表、异步生成及内容下载能力,不表示支持 OpenAI 全部 API。
该接口面向需要接入 OpenAI / Sora 风格视频协议的平台,例如 NewAPI 等聚合平台。接口使用平台 API Key 鉴权。
创建任务时,model 必须使用模型列表接口返回的完整 ID,格式为 {channelCode}:{model}。
/v1/videos 是异步生成入口:传入视频模型时创建视频任务,传入图片模型时创建图片任务。为了兼容已经适配 OpenAI/Sora 视频协议的下游平台,图片生成也通过 /v1/videos 创建和查询,不使用 OpenAI 官方同步图片接口。
通用说明
所有接口均需要通过请求头传递 API Key:
表格较宽时,可左右滑动查看完整内容。
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| Authorization | Header | string | 是 | 固定格式:Bearer {apiKey} |
- API Key 与平台账号绑定,仅能访问该账号下的任务和资源。
- 模型、线路、价格和能力会随运营策略调整,客户端应通过模型列表接口动态读取,不应写死模型 ID。
- OpenAI 兼容视频接口路径为
/v1/videos。 - OpenAI 兼容模型列表接口路径为
/v1/models。 - 返回对象仍保持 OpenAI/Sora 视频对象结构,
object固定为video;图片任务完成后的图片 URL 同样放在metadata.result_url。
推荐调用流程
- 调用
GET /v1/models获取当前可用模型列表。 - 从模型列表中选择
data[].id,创建任务时原样传入model。 - 调用
POST /v1/videos创建生成任务;传视频模型生成视频,传图片模型生成图片。 - 使用创建接口返回的
id调用GET /v1/videos/{video_id}轮询任务状态。 - 任务
status=completed后,可读取metadata.result_url,或调用GET /v1/videos/{video_id}/content获取 302 下载跳转。
任务状态
表格较宽时,可左右滑动查看完整内容。
| 状态值 | 说明 |
|---|---|
| queued | 已创建,等待执行 |
| in_progress | 执行中 |
| completed | 任务成功完成 |
| failed | 任务执行失败 |
错误响应
接口失败时返回 OpenAI 兼容错误结构:
json
{
"error": {
"message": "model not found",
"type": "invalid_request_error",
"param": "model",
"code": "model_ambiguous"
}
}常见错误码:
表格较宽时,可左右滑动查看完整内容。
| HTTP 状态码 | code | 说明 |
|---|---|---|
| 400 | invalid_request | 请求体缺失或字段格式不合法 |
| 400 | model_ambiguous | model 未使用模型列表返回的完整 ID,或无法匹配当前可用模型 |
| 400 | invalid_metadata | metadata 字段格式不合法,或传入不支持的扩展字段 |
| 400 | unsupported_parameter | 当前参数值暂不支持,例如 n 不为 1、variant 不为 video 或 image |
| 400 | video_not_completed | 内容下载接口请求的任务尚未完成 |
| 400 | content_not_available | 任务已完成但内容地址不可用 |
| 401 | invalid_api_key | API Key 缺失、格式错误、已禁用或不存在 |
| 404 | not_found | 任务不存在,或不属于当前 API Key 对应账号 |
| 429 | rate_limit_exceeded | API Key 鉴权保护限制,按 Retry-After 等待并修正鉴权;见错误处理 |
| 500 | internal_error | 服务内部异常 |
获取模型列表
bash
curl 'https://api.video.aistarslab.com/openai/v1/models' \
-H "Authorization: Bearer $AISTARSLAB_API_KEY"作用:获取当前可用于兼容接口的模型列表,包含图片模型和视频模型。
请求:GET /v1/models
注意:由于 OpenAI 模型列表协议限制,仅能下发模型 ID、归属方等基础信息,无法完整表达模型类型、支持参数、画幅比例、时长、质量档位、价格等能力。调用方如需查看模型完整能力,请前往官网查看,或调用 OpenAPI 的 config 配置接口获取。
输入参数
无。
返回参数
HTTP 200:
表格较宽时,可左右滑动查看完整内容。
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| object | string | 是 | 固定为 list |
| data | array<ModelItem> | 是 | 当前可用模型列表 |
ModelItem
表格较宽时,可左右滑动查看完整内容。
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 创建任务时使用的模型 ID,必须原样传入 model |
| object | string | 是 | 固定为 model |
| created | integer | 是 | 创建时间戳;暂无创建时间时为 0 |
| owned_by | string | 是 | 模型归属方 |
返回示例
json
{
"object": "list",
"data": [
{
"id": "12:example-video-model",
"object": "model",
"created": 0,
"owned_by": "aistarslab"
}
]
}测试模型
为方便下游联调生成协议,平台提供隐藏测试模型:
表格较宽时,可左右滑动查看完整内容。
| 类型 | model |
|---|---|
| 视频测试 | test:test-video |
| 图片测试 | test:test-image |
- 测试模型不会出现在
GET /v1/models返回中。 - 使用测试模型创建任务不会扣积分、不会产生实际数据、不会调用上游。
- 视频测试任务 ID 以
test_video_开头,图片测试任务 ID 以test_image_开头。 - 查询测试任务会固定返回
completed测试数据和测试输出 URL。 - 测试模型仅用于联调鉴权、创建、轮询和结果解析,不代表真实生成能力。
测试模型创建视频请求示例
json
{
"model": "test:test-video",
"prompt": "测试视频生成接口",
"seconds": "5",
"size": "16:9",
"n": 1
}测试模型创建图片请求示例
json
{
"model": "test:test-image",
"prompt": "测试图片生成接口",
"size": "16:9",
"n": 1,
"metadata": {
"resolution": "1K"
}
}创建生成任务
作用:创建异步生成任务,并返回 OpenAI 风格视频对象。传入视频模型时生成视频,传入图片模型时生成图片。
请求:POST /v1/videos
Content-Type:application/json
输入参数
表格较宽时,可左右滑动查看完整内容。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型列表接口返回的 data[].id,必须原样传入 |
| prompt | string | 是 | 生成提示词。图片模型最长 5000 字符,视频模型最长 15000 字符,部分线路可能有更短限制 |
| image | string | 否 | 单张参考图片 URL;会作为参考图片列表的第一张 |
| seconds | string | 否 | 视频任务时长,单位:秒;优先级高于 duration;图片任务忽略 |
| duration | integer | 否 | 视频任务时长,单位:秒;未传 seconds 时生效;图片任务忽略 |
| size | string | 否 | 画幅比例,如 16:9、9:16、1:1;图片和视频均优先使用该字段,未传或为空时读取 metadata.size,再尝试宽高换算和默认比例 |
| width | integer | 否 | 期望宽度,正整数;size 与 metadata.size 均未传或为空、且宽高都提供时,与 height 换算画幅比例 |
| height | integer | 否 | 期望高度,正整数;生效条件同 width |
| n | integer | 否 | 生成数量;当前仅支持 1 |
| metadata | object | 否 | 平台扩展参数 |
metadata 扩展参数
表格较宽时,可左右滑动查看完整内容。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| resolution | string | 否 | 分辨率或质量档位,如 720p、1080p、1K;图片任务未传时自动选择模型默认值 |
| size | string | 否 | 画面比例,如 16:9、9:16;仅在顶层 size 未传或为空时生效,适用于图片和视频 |
| mode_type | string | 否 | 视频生成模式:text2video、image2video、frames2video;图片任务忽略 |
| images | array<string> | 否 | 参考图片 URL 列表;会追加在顶层 image 之后 |
| videos | array<string> | 否 | 视频任务参考视频 URL 列表;图片任务忽略 |
| audios | array<string> | 否 | 视频任务参考音频 URL 列表;图片任务忽略 |
画幅比例优先级
图片和视频均按 size → metadata.size → width/height → 默认比例 的顺序选择画幅,空白字符串按未传处理。
size和metadata.size均未传或为空时,只有width与height都提供才换算,例如 1920 × 1080 得到16:9。- 只提供宽或高时不参与换算。所有已提供的宽高都必须为正整数,即使已传
size也会校验。 - 没有可用比例或完整宽高时,视频默认
16:9;真实图片模型优先1:1,否则选模型支持的第一个比例。 - 隐藏测试模型返回固定测试数据,不用于检验实际输出画幅。
width 与 height 保留兼容支持;新接入建议直接使用 size 表达画幅。画面清晰度由 metadata.resolution 设置,宽高换算不决定实际输出分辨率。
mode_type 规则
表格较宽时,可左右滑动查看完整内容。
| 模式 | 说明 | 素材要求 |
|---|---|---|
| text2video | 文生视频 | 不允许传入参考图片、参考视频或参考音频 |
| image2video | 全能参考 | 至少传入 1 个参考素材,可按线路能力组合参考图片、参考视频、参考音频 |
| frames2video | 首尾帧生视频 | 必须正好传入 2 张参考图片,顺序为首帧、尾帧 |
mode_type必须被所选模型和线路支持。- 未显式传入
mode_type时:存在任意参考图片、参考视频或参考音频则按image2video(全能参考)处理,否则按text2video处理。 - 部分线路对参考图片、视频、音频数量或组合方式有额外限制,具体以创建接口实时校验为准。
图片模型规则
- 图片模型同样通过
POST /v1/videos创建异步任务。 - 图片任务按
size→metadata.size→width/height→ 默认比例的顺序选择画幅;空白字符串按未传处理。 - 两处比例均未传且未提供完整宽高时,图片默认优先
1:1,否则使用所选模型支持的第一个比例。 - 图片任务的质量/清晰度使用
metadata.resolution;未传时服务端自动选择模型默认质量。 - 图片任务响应中的
object仍固定为video,生成结果 URL 位于metadata.result_url。
可运行的测试请求
设置环境变量 AISTARSLAB_API_KEY 后可直接运行,不扣生成积分。
bash
curl 'https://api.video.aistarslab.com/openai/v1/videos' \
-H "Authorization: Bearer $AISTARSLAB_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"model":"test:test-video","prompt":"测试生成","seconds":"5","size":"16:9","n":1}'请求结构示例
下方正式模型与素材 URL 仅演示结构,需要替换为实际可用值。
json
{
"model": "12:example-video-model",
"prompt": "海边日落,镜头缓慢向前推进,背景 @图片1,画面节奏参考音乐 @音频1",
"seconds": "10",
"size": "16:9",
"n": 1,
"metadata": {
"resolution": "720p",
"mode_type": "image2video",
"images": [
"https://example.com/reference.jpg"
],
"audios": [
"https://example.com/music.mp3"
]
}
}图片模型请求示例
json
{
"model": "21:example-image-model",
"prompt": "一只白色陶瓷杯放在木桌上,柔和自然光,产品摄影",
"size": "1:1",
"n": 1,
"metadata": {
"resolution": "1K"
}
}返回参数
HTTP 200:
表格较宽时,可左右滑动查看完整内容。
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 任务 ID,用于查询任务和获取内容 |
| object | string | 是 | 固定为 video |
| model | string | 否 | 任务模型名;创建新任务仍须使用模型列表中的完整 ID |
| status | string | 是 | 任务状态,见“任务状态” |
| progress | integer | 否 | 任务进度,范围 0-100 |
| seconds | string | 否 | 视频时长,单位:秒;图片任务为空 |
| size | string | 否 | 视频或图片画幅比例 |
| created_at | integer | 否 | 创建时间,Unix 秒 |
| completed_at | integer | 否 | 完成时间,Unix 秒;未完成时为空 |
| metadata | object | 否 | 扩展元信息,完成后可能包含 result_url |
| error | object | 否 | 任务失败时的错误信息 |
返回示例
json
{
"id": "task_xxxxx",
"object": "video",
"model": "example-video-model",
"status": "queued",
"progress": 0,
"seconds": "10",
"size": "16:9",
"created_at": 1781539200
}查询生成任务
将 YOUR_TASK_ID 替换为创建响应中的 id。
bash
curl 'https://api.video.aistarslab.com/openai/v1/videos/YOUR_TASK_ID' \
-H "Authorization: Bearer $AISTARSLAB_API_KEY"作用:查询生成任务状态和结果。
请求:GET /v1/videos/{video_id}
输入参数
表格较宽时,可左右滑动查看完整内容。
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| video_id | Path | string | 是 | 创建接口返回的 id |
返回参数
HTTP 200:同“创建生成任务”的返回结构。
返回示例:处理中
json
{
"id": "task_xxxxx",
"object": "video",
"model": "example-video-model",
"status": "in_progress",
"progress": 45,
"seconds": "10",
"size": "16:9",
"created_at": 1781539200
}返回示例:已完成
json
{
"id": "task_xxxxx",
"object": "video",
"model": "example-video-model",
"status": "completed",
"progress": 100,
"seconds": "10",
"size": "16:9",
"created_at": 1781539200,
"completed_at": 1781539260,
"metadata": {
"result_url": "https://example.com/result.mp4"
}
}返回示例:图片任务已完成
json
{
"id": "task_xxxxx",
"object": "video",
"model": "example-image-model",
"status": "completed",
"progress": 100,
"size": "1:1",
"created_at": 1781539200,
"completed_at": 1781539260,
"metadata": {
"result_url": "https://example.com/result.png"
}
}返回示例:失败
json
{
"id": "task_xxxxx",
"object": "video",
"model": "example-video-model",
"status": "failed",
"progress": 100,
"seconds": "10",
"size": "16:9",
"created_at": 1781539200,
"completed_at": 1781539260,
"error": {
"code": "task_failed",
"message": "生成失败,请检查文案或素材"
}
}获取生成内容
作用:获取生成完成后的内容地址。接口返回 302 重定向,客户端应跟随 Location 下载或播放真实文件。
请求:GET /v1/videos/{video_id}/content
输入参数
表格较宽时,可左右滑动查看完整内容。
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| video_id | Path | string | 是 | 创建接口返回的 id |
| variant | Query | string | 否 | 支持空值、video、image;图片任务可传 image |
成功响应
HTTP 302:
表格较宽时,可左右滑动查看完整内容。
| Header | 说明 |
|---|---|
| Location | 真实内容文件 URL |
请求示例
bash
curl -L 'https://api.video.aistarslab.com/openai/v1/videos/task_xxxxx/content?variant=video' \
-H "Authorization: Bearer $AISTARSLAB_API_KEY"