跳到主要内容

文件上传 - POST /v1/files/upload - 上传文件获取 URL

POST 
/v1/files/upload

基本信息​

  • Base URL：https://api.dshub.top
  • 主端点：POST /v1/files/upload
  • 兼容端点：POST /v1/files、POST /v1/uploads
  • Content-Type：multipart/form-data
  • 用途：先把本地图片或视频上传到平台 OSS，拿到公网 URL 后，再把 URL 传给生图、生视频等模型接口。

返回 URL 说明​

上传成功后，请使用响应里的 url（或 cdn_url）作为后续生图 / 生视频接口的参考素材地址。一般为 https://api-oss.dshub.top/... 形式的公网 URL。

若下游是 Seedance 低价参考音视频：音频建议 MP3 / WAV、单段 2–30 秒、≤15MB；视频建议 MP4 / MOV、单段 2–30 秒、≤200MB（详见 Seedance 低价创建接口文档）。本上传接口本身的体积上限见下文「文件限制」。

适用场景​

  • 用户本地只有文件，没有公网 URL。
  • 国产服务器或客户网络访问外部图片 URL 不稳定，希望先上传到平台 OSS，再提交任务。
  • Grok Video、Veo、Nano Banana 等接口需要参考图 URL 时，可先调用本接口获取稳定 URL。

鉴权与计费​

  • 必须使用 Authorization: Bearer sk-xxx，token 是控制台创建的完整 API Key。
  • 上传接口只做文件入库和 OSS 转存，不走模型渠道分发，不消耗模型额度，也不会触发模型渠道重试。
  • 文件会归属到该 API Key 对应的用户账号下。

文件限制​

  • 图片最大 40MB。
  • 视频最大 80MB。
  • 其他文件类型暂按通用请求体上限 80MB 处理。
  • 支持常见图片：PNG、JPEG、WebP、GIF。
  • 支持常见视频：MP4、MOV、WebM。

保存时间​

  • 资产记录默认保留 365 天，返回字段 expires_at 表示资产过期时间。
  • 如果返回的是平台本地签名 URL，url_expires_at 表示该 URL 本身的过期时间；过期后可重新上传或从资产库重新生成访问地址。
  • 如果返回的是 OSS/CDN 公网 URL，通常没有短期签名过期时间。

请求字段​

字段类型必填说明
filefile是要上传的本地文件。
typestring否文件类型，可传 image、video、audio、document、text。不传时按文件 MIME 或扩展名识别。
purposestring否用途标记，例如 reference_image、input_video。不影响上传，只方便调用方区分用途。
namestring否展示名称，不传则使用原文件名。
recordIdstring否自定义记录 ID。一般不需要传，平台会自动生成。

返回字段​

  • url：推荐直接给模型接口使用的公网 URL。
  • cdn_url：OSS/CDN 公网地址。
  • thumbnail_url：如果平台生成了缩略图，会返回缩略图地址。
  • sha256：文件内容哈希，可用于去重或排查问题。

cURL：上传参考图​

curl --location --request POST 'https://api.dshub.top/v1/files/upload' \
  --header 'Authorization: Bearer sk-xxx' \
  --form 'purpose="reference_image"' \
  --form 'type="image"' \
  --form 'file=@"/path/to/reference.png"'

cURL：上传输入视频​

curl --location --request POST 'https://api.dshub.top/v1/files/upload' \
  --header 'Authorization: Bearer sk-xxx' \
  --form 'purpose="input_video"' \
  --form 'type="video"' \
  --form 'file=@"/path/to/input.mp4"'

后续使用​

上传成功后，把返回的 url 填到下游模型接口中，例如：

{
  "model": "grok-video-1.5",
  "prompt": "让参考图里的产品缓慢旋转，保持主体结构不变",
  "image_urls": ["{{上传接口返回的 url}}"],
  "seconds": 10,
  "resolution": "720p"
}

常见错误​

  • 401：没有传 API Key，或 API Key 无效。
  • 413：文件超过限制，图片请控制在 40MB 内，视频请控制在 80MB 内。
  • 502：对象存储写入失败，可以稍后重试。

Request​

Responses​

上传成功

Response Headers