主题
素材上传
Base URL:https://api.video.aistarslab.com/openapi,下方路径均相对于此地址。
使用说明
素材上传接口是可选的辅助能力,主要提供给没有自有图床、对象存储或其他公网素材托管能力的用户使用。你可以通过该接口将本地图片、音频或视频上传至平台对象存储,获取可用于图片或视频生成的公网 URL。
素材类型须被所选生成模型支持。上传文件保留 3 天,过期后会自动清理,请勿作为长期存储使用。
OpenAPI 接口均需要通过请求头传递 API Key:
表格较宽时,可左右滑动查看完整内容。
| 参数名 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| Authorization | Header | string | 是 | 固定格式:Bearer {apiKey} |
统一返回结构:
表格较宽时,可左右滑动查看完整内容。
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | integer | 是 | 返回码,0 表示成功,其他表示异常 |
| msg | string | 是 | 返回消息,成功时为 success |
| data | object / array | 否 | 接口返回数据 |
上传由以下三个步骤组成:
- 调用
POST /uploads/presign获取上传预签名。 - 使用预签名返回的 URL、请求方法和全部请求头,将文件直接上传至对象存储。
- 调用
POST /uploads/complete完成文件校验和积分扣减。
签名过期或上传失败的处理见错误处理与轮询。
素材限制
表格较宽时,可左右滑动查看完整内容。
| 素材类型 | 最大文件大小 | 支持的 MIME 类型 | 常用文件后缀 |
|---|---|---|---|
| 图片 | 20 MiB | image/jpeg、image/png、image/gif、image/bmp、image/webp | jpg、jpeg、png、gif、bmp、webp |
| 音频 | 20 MiB | audio/mpeg、audio/mp3、audio/wav、audio/wave、audio/x-wav | mp3、wav |
| 视频 | 100 MiB | video/mp4、video/quicktime、video/x-msvideo、video/x-ms-wmv、video/x-flv、video/x-matroska、video/webm、video/3gpp、video/3gpp2、video/avi、video/mpeg、video/ogg、video/x-m4v | mp4、mov、avi、wmv、flv、mkv、webm、3gp、mpeg、mpg、ogv、m4v |
- 文件大小单位为字节,
1 MiB = 1024 × 1024 bytes。 - 文件名包含后缀时,后缀必须与提交的 MIME 类型匹配。
- 上传至对象存储的文件大小和
Content-Type必须与预签名请求完全一致。
计费规则
- 每上传
3 MiB素材扣除 1 积分,不足3 MiB的部分向上取整。 - 获取预签名不会扣除积分,返回的
expectedCostCredits为预计扣费积分。 - 文件直传成功后,调用完成确认接口并通过校验时实际扣除积分。
- 完成确认接口支持幂等调用,重复确认同一
fileKey不会重复扣费。 - 积分不足时完成确认失败,已上传文件不能用于图片或视频生成。
获取上传预签名
作用:校验素材参数,创建上传记录并返回对象存储预签名。
请求:POST /uploads/presign
Content-Type:application/json
输入参数
表格较宽时,可左右滑动查看完整内容。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| filename | string | 是 | 原始文件名,最长 255 字符;包含后缀时必须与 contentType 匹配 |
| contentType | string | 是 | 文件 MIME 类型,最长 100 字符,必须为支持的素材类型 |
| size | integer | 是 | 文件大小,单位:字节,必须大于 0 |
请求示例
json
{
"filename": "reference.png",
"contentType": "image/png",
"size": 1048576
}返回参数
HTTP 200 且 response.code=0 时,response.data:
表格较宽时,可左右滑动查看完整内容。
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fileKey | string | 是 | 对象存储文件 Key,完成确认时原样提交 |
| uploadUrl | string | 是 | 对象存储预签名上传 URL |
| method | string | 是 | 上传请求方法,当前为 PUT |
| headers | object | 是 | 上传对象存储时必须携带的全部签名请求头 |
| expireSeconds | integer | 是 | 预签名 URL 有效期,单位:秒 |
| expectedCostCredits | integer | 是 | 按申请上传的文件大小计算的预计扣费积分 |
响应示例
json
{
"code": 0,
"msg": "success",
"data": {
"fileKey": "materials/images/20260615/example.png",
"uploadUrl": "https://example.cos.ap-shanghai.myqcloud.com/materials/images/20260615/example.png?signature=...",
"method": "PUT",
"headers": {
"Content-Type": "image/png",
"Content-Length": "1048576",
"x-cos-forbid-overwrite": "true"
},
"expireSeconds": 3600,
"expectedCostCredits": 1
}
}上传文件至对象存储
使用预签名接口返回的 uploadUrl、method 和 headers 直接上传文件。该请求发送至对象存储,不需要携带 OpenAPI 的 Authorization 请求头。
客户端必须原样携带预签名接口返回的全部签名请求头。请求体为文件原始二进制内容,不使用 multipart/form-data 包装。
以下为命令行示例,实际请求头及 URL 应使用预签名接口的实时返回值:
bash
curl --request PUT \
--url 'https://example.cos.ap-shanghai.myqcloud.com/materials/images/20260615/example.png?signature=...' \
--header 'Content-Type: image/png' \
--header 'Content-Length: 1048576' \
--header 'x-cos-forbid-overwrite: true' \
--upload-file './reference.png'对象存储返回 HTTP 2xx 表示文件上传成功。随后必须调用完成确认接口,否则文件不能作为有效素材使用。
完成上传确认
作用:校验对象存储中的实际文件与预签名记录是否一致,完成上传记录并扣除积分。
请求:POST /uploads/complete
Content-Type:application/json
输入参数
表格较宽时,可左右滑动查看完整内容。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fileKey | string | 是 | 预签名接口返回的对象存储文件 Key,最长 512 字符 |
请求示例
json
{
"fileKey": "materials/images/20260615/example.png"
}返回参数
HTTP 200 且 response.code=0 时,response.data:
表格较宽时,可左右滑动查看完整内容。
| 属性名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fileKey | string | 是 | 对象存储文件 Key |
| url | string | 是 | 带访问鉴权签名的素材公网 URL,可用于图片或视频生成任务 |
| size | integer | 是 | 文件大小,单位:字节 |
| contentType | string | 是 | 文件 MIME 类型 |
| costCredits | integer | 是 | 该素材上传消耗的积分;重复确认时返回原扣费值,不会再次扣费 |
响应示例
json
{
"code": 0,
"msg": "success",
"data": {
"fileKey": "materials/images/20260615/example.png",
"url": "https://cdn.example.com/materials/images/20260615/example.png?sign=...",
"size": 1048576,
"contentType": "image/png",
"costCredits": 1
}
}Python 完整调用示例
以下代码仅依赖 Python 3 标准库,自动完成预签名、上传对象存储和完成确认三个步骤。
设置环境变量 AISTARSLAB_API_KEY,修改 FILE_PATH 为实际文件。每次网络请求最多等待 30 秒;不要把真实 Key 写入脚本。
python
import json
import os
import mimetypes
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen
BASE_URL = "https://api.video.aistarslab.com/openapi"
API_KEY = os.environ["AISTARSLAB_API_KEY"]
FILE_PATH = Path("./reference.png")
def openapi_post(path, body):
request = Request(
f"{BASE_URL}{path}",
data=json.dumps(body).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urlopen(request, timeout=30) as response:
result = json.loads(response.read().decode("utf-8"))
if result.get("code") != 0:
raise RuntimeError(f"接口请求失败:{result}")
return result["data"]
def main():
file_data = FILE_PATH.read_bytes()
content_type = mimetypes.guess_type(FILE_PATH.name)[0]
if not content_type:
raise ValueError("无法识别文件 MIME 类型,请检查文件后缀")
presign = openapi_post(
"/uploads/presign",
{
"filename": FILE_PATH.name,
"contentType": content_type,
"size": len(file_data),
},
)
print(f"预计扣费:{presign['expectedCostCredits']} 积分")
upload_request = Request(
presign["uploadUrl"],
data=file_data,
headers=presign["headers"],
method=presign["method"],
)
with urlopen(upload_request, timeout=30) as response:
if not 200 <= response.status < 300:
raise RuntimeError(f"对象存储上传失败:HTTP {response.status}")
completed = openapi_post(
"/uploads/complete",
{"fileKey": presign["fileKey"]},
)
print(f"实际扣费:{completed['costCredits']} 积分")
print(f"素材地址:{completed['url']}")
if __name__ == "__main__":
try:
main()
except HTTPError as error:
detail = error.read().decode("utf-8", errors="replace")
raise RuntimeError(f"HTTP 请求失败:{error.code} {detail}") from error