Skip to content

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:

表格较宽时,可左右滑动查看完整内容。

参数名位置类型必填说明
AuthorizationHeaderstring是固定格式:Bearer {apiKey}
  • API Key 与平台账号绑定,仅能访问该账号下的任务和资源。
  • 模型、线路、价格和能力会随运营策略调整,客户端应通过模型列表接口动态读取,不应写死模型 ID。
  • OpenAI 兼容视频接口路径为 /v1/videos。
  • OpenAI 兼容模型列表接口路径为 /v1/models。
  • 返回对象仍保持 OpenAI/Sora 视频对象结构,object 固定为 video;图片任务完成后的图片 URL 同样放在 metadata.result_url。

推荐调用流程 ​

  1. 调用 GET /v1/models 获取当前可用模型列表。
  2. 从模型列表中选择 data[].id,创建任务时原样传入 model。
  3. 调用 POST /v1/videos 创建生成任务;传视频模型生成视频,传图片模型生成图片。
  4. 使用创建接口返回的 id 调用 GET /v1/videos/{video_id} 轮询任务状态。
  5. 任务 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说明
400invalid_request请求体缺失或字段格式不合法
400model_ambiguousmodel 未使用模型列表返回的完整 ID,或无法匹配当前可用模型
400invalid_metadatametadata 字段格式不合法,或传入不支持的扩展字段
400unsupported_parameter当前参数值暂不支持,例如 n 不为 1、variant 不为 video 或 image
400video_not_completed内容下载接口请求的任务尚未完成
400content_not_available任务已完成但内容地址不可用
401invalid_api_keyAPI Key 缺失、格式错误、已禁用或不存在
404not_found任务不存在,或不属于当前 API Key 对应账号
429rate_limit_exceededAPI Key 鉴权保护限制,按 Retry-After 等待并修正鉴权;见错误处理
500internal_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:

表格较宽时,可左右滑动查看完整内容。

属性名类型必填说明
objectstring是固定为 list
dataarray<ModelItem>是当前可用模型列表

ModelItem ​

表格较宽时,可左右滑动查看完整内容。

属性名类型必填说明
idstring是创建任务时使用的模型 ID,必须原样传入 model
objectstring是固定为 model
createdinteger是创建时间戳;暂无创建时间时为 0
owned_bystring是模型归属方

返回示例 ​

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

输入参数 ​

表格较宽时,可左右滑动查看完整内容。

参数名类型必填说明
modelstring是模型列表接口返回的 data[].id,必须原样传入
promptstring是生成提示词。图片模型最长 5000 字符,视频模型最长 15000 字符,部分线路可能有更短限制
imagestring否单张参考图片 URL;会作为参考图片列表的第一张
secondsstring否视频任务时长,单位:秒;优先级高于 duration;图片任务忽略
durationinteger否视频任务时长,单位:秒;未传 seconds 时生效;图片任务忽略
sizestring否画幅比例,如 16:9、9:16、1:1;图片和视频均优先使用该字段,未传或为空时读取 metadata.size,再尝试宽高换算和默认比例
widthinteger否期望宽度,正整数;size 与 metadata.size 均未传或为空、且宽高都提供时,与 height 换算画幅比例
heightinteger否期望高度,正整数;生效条件同 width
ninteger否生成数量;当前仅支持 1
metadataobject否平台扩展参数

metadata 扩展参数 ​

表格较宽时,可左右滑动查看完整内容。

参数名类型必填说明
resolutionstring否分辨率或质量档位,如 720p、1080p、1K;图片任务未传时自动选择模型默认值
sizestring否画面比例,如 16:9、9:16;仅在顶层 size 未传或为空时生效,适用于图片和视频
mode_typestring否视频生成模式:text2video、image2video、frames2video;图片任务忽略
imagesarray<string>否参考图片 URL 列表;会追加在顶层 image 之后
videosarray<string>否视频任务参考视频 URL 列表;图片任务忽略
audiosarray<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:

表格较宽时,可左右滑动查看完整内容。

属性名类型必填说明
idstring是任务 ID,用于查询任务和获取内容
objectstring是固定为 video
modelstring否任务模型名;创建新任务仍须使用模型列表中的完整 ID
statusstring是任务状态,见“任务状态”
progressinteger否任务进度,范围 0-100
secondsstring否视频时长,单位:秒;图片任务为空
sizestring否视频或图片画幅比例
created_atinteger否创建时间,Unix 秒
completed_atinteger否完成时间,Unix 秒;未完成时为空
metadataobject否扩展元信息,完成后可能包含 result_url
errorobject否任务失败时的错误信息

返回示例 ​

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_idPathstring是创建接口返回的 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_idPathstring是创建接口返回的 id
variantQuerystring否支持空值、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"

星辰 AI · 图片与视频生成 API