Skip to content

素材上传 ​

Base URL:https://api.video.aistarslab.com/openapi,下方路径均相对于此地址。

使用说明 ​

素材上传接口是可选的辅助能力,主要提供给没有自有图床、对象存储或其他公网素材托管能力的用户使用。你可以通过该接口将本地图片、音频或视频上传至平台对象存储,获取可用于图片或视频生成的公网 URL。

素材类型须被所选生成模型支持。上传文件保留 3 天,过期后会自动清理,请勿作为长期存储使用。

OpenAPI 接口均需要通过请求头传递 API Key:

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

参数名位置类型必填说明
AuthorizationHeaderstring是固定格式:Bearer {apiKey}

统一返回结构:

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

属性名类型必填说明
codeinteger是返回码,0 表示成功,其他表示异常
msgstring是返回消息,成功时为 success
dataobject / array否接口返回数据

上传由以下三个步骤组成:

  1. 调用 POST /uploads/presign 获取上传预签名。
  2. 使用预签名返回的 URL、请求方法和全部请求头,将文件直接上传至对象存储。
  3. 调用 POST /uploads/complete 完成文件校验和积分扣减。

签名过期或上传失败的处理见错误处理与轮询。

素材限制 ​

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

素材类型最大文件大小支持的 MIME 类型常用文件后缀
图片20 MiBimage/jpeg、image/png、image/gif、image/bmp、image/webpjpg、jpeg、png、gif、bmp、webp
音频20 MiBaudio/mpeg、audio/mp3、audio/wav、audio/wave、audio/x-wavmp3、wav
视频100 MiBvideo/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-m4vmp4、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

输入参数 ​

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

参数名类型必填说明
filenamestring是原始文件名,最长 255 字符;包含后缀时必须与 contentType 匹配
contentTypestring是文件 MIME 类型,最长 100 字符,必须为支持的素材类型
sizeinteger是文件大小,单位:字节,必须大于 0

请求示例 ​

json
{
  "filename": "reference.png",
  "contentType": "image/png",
  "size": 1048576
}

返回参数 ​

HTTP 200 且 response.code=0 时,response.data:

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

属性名类型必填说明
fileKeystring是对象存储文件 Key,完成确认时原样提交
uploadUrlstring是对象存储预签名上传 URL
methodstring是上传请求方法,当前为 PUT
headersobject是上传对象存储时必须携带的全部签名请求头
expireSecondsinteger是预签名 URL 有效期,单位:秒
expectedCostCreditsinteger是按申请上传的文件大小计算的预计扣费积分

响应示例 ​

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

输入参数 ​

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

参数名类型必填说明
fileKeystring是预签名接口返回的对象存储文件 Key,最长 512 字符

请求示例 ​

json
{
  "fileKey": "materials/images/20260615/example.png"
}

返回参数 ​

HTTP 200 且 response.code=0 时,response.data:

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

属性名类型必填说明
fileKeystring是对象存储文件 Key
urlstring是带访问鉴权签名的素材公网 URL,可用于图片或视频生成任务
sizeinteger是文件大小,单位:字节
contentTypestring是文件 MIME 类型
costCreditsinteger是该素材上传消耗的积分;重复确认时返回原扣费值,不会再次扣费

响应示例 ​

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

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