跳转到主要内容
POST
上传参考素材,成功后直接返回公网 URL,无需轮询。上传本身免费,但账户余额必须大于 0。三个上传接口共享同一用户的文件额度,默认 72 小时内合计最多 2000 个文件。
文档 Playground 不支持文件上传,请使用下方 cURL、Python 或 JavaScript 示例。JavaScript 示例需要页面中有已选择文件的 <input type="file">。

认证

string
必填
使用有效、未禁用、未过期的 APIMart API Key,格式为 Bearer <token>,且账号未被封禁。账户余额必须大于 0;Key 自身额度用完仍可上传。可在 API Key 管理页面 获取 Key。

请求参数

file
必填
通过 multipart/form-data 的 file 字段传入一个带文件名的文件。不要使用 JSON、base64 字符串或文件 URL 代替文件部分。其他表单字段会被忽略;同一请求传入多个 file 时只处理第一个。支持格式: MP4 (.mp4), MOV (.mov), WebM (.webm)默认单文件上限: 50MB。单文件上限可调整,以实际服务配置和超限错误提示为准。
使用 cURL --form、Python files 或 JavaScript FormData 时,由客户端自动生成包含 boundary 的 Content-Type,不要手动设置该请求头。

文件校验

文件类型按实际内容识别,不依赖扩展名或客户端声明的 MIME 类型。文件内容必须与上传接口匹配;改扩展名不能转换格式,类型不匹配会返回 HTTP 400。 视频会校验容器结构,伪造文件头或损坏的容器会被拒绝。仅支持下列格式,不能通过修改文件名上传 AVI、MKV 等其他格式。

成功响应

HTTP 200 返回文件信息,url 位于 JSON 顶层,没有 data 包装,也不返回生成任务 ID。
string
文件公网 URL。将其填入目标生成接口对应的参考素材参数;该模型仍有独立的格式、大小、数量、时长等限制,上传成功不代表一定符合模型要求。
string
原始文件名。
string
服务端按文件内容识别的 MIME 类型,不是客户端声明的值。
string
文件类别,本接口返回 video。
integer
实际文件大小,单位为字节。
integer
上传时间,Unix 时间戳,单位为秒。
object
可选的上传额度信息。普通受限用户的字段如下;不限额或统计暂不可用时,结构可能不同,见下方说明。

共享额度与请求限速

图片、视频和音频三个接口按用户共享额度,同一用户的多个 API Key 不叠加额度。窗口按整点滚动,默认统计最近约 71–72 小时的成功上传。格式错误、超出大小或存储失败的上传不占文件额度。 普通受限响应同时提供 X-Upload-Quota-Limit、X-Upload-Quota-Remaining、X-Upload-Quota-Reset,分别对应 limit、remaining、reset_at;Reset 的单位是 Unix 秒。 不限额用户返回 quota: {"unlimited": true},不带上述三个额度响应头。统计暂不可用时,成功响应可能省略 quota;此时不要按 0 或不限额解析,也不要因为缺少额度信息而重复上传。 文件额度耗尽时返回 HTTP 429,error.type 为 rate_limit_exceeded,响应附带 quota(remaining: 0)和 Retry-After。按 Retry-After 指定的秒数等待后重试。另有每个 Key 每 60 秒 1000 次请求的限速,对应 rate_limit_error,与文件额度独立。

错误处理

错误对象位于 JSON 顶层的 error 中,通过 HTTP 状态码、error.type / error.code 和 error.message 判断原因。

URL 使用与文件保存

72 小时是默认额度统计窗口,不是文件保存时长承诺。文件保留期限以存储策略为准,请保留原始文件,并在取得 URL 后及时用于生成;不要假定 URL 永久有效。

其他上传接口