文件上传接口

使用 POST https://file.reachapi.ai/file/uploads 上传本地图片、音频或视频文件。上传成功后，接口会在 data.url 返回一个临时 HTTPS URL，可传给需要公网文件地址的模型接口。

当文件只存在于本地设备或私有环境时，先调用该接口上传文件。如果你已经有目标模型可访问的公网 HTTPS 文件地址，可以直接传该地址，不一定需要先上传到 ReachAPI。

1. 接口概览

项目	说明
请求方法	`POST`
请求地址	`https://file.reachapi.ai/file/uploads`
认证方式	`Authorization: Bearer YOUR_REACH_API_KEY`
请求类型	`multipart/form-data`
文件字段	`file`
上传模式	单文件上传
文件大小上限	`52428800` bytes，约 `50MB`

请求头：

Authorization: Bearer YOUR_REACH_API_KEY
Content-Type: multipart/form-data

使用 curl、SDK 上传工具或 FormData 时，让客户端自动生成 multipart boundary。

2. 上传请求

2.1 cURL 示例

curl -sS -X POST "https://file.reachapi.ai/file/uploads" \
  -H "Authorization: Bearer YOUR_REACH_API_KEY" \
  -F "file=@/path/to/file.mp4;type=video/mp4"

2.2 请求字段

字段	类型	必填	说明
`file`	binary	是	要上传的本地图片、音频或视频文件。不需要额外传文件类型字段。

3. 支持的文件类型

文件类型	支持的 MIME	返回的 `file_kind`
图片	`image/png`、`image/jpeg`、`image/jpg`、`image/webp`、`image/gif`	`image`
音频	`audio/mpeg`、`audio/mp3`、`audio/wav`、`audio/x-wav`、`audio/mp4`、`audio/aac`、`audio/ogg`、`audio/webm`	`audio`
视频	`video/mp4`、`video/webm`、`video/quicktime`、`video/x-matroska`	`video`

说明：

image/jpg 会归一为 image/jpeg
audio/mp3 会归一为 audio/mpeg
audio/x-wav 会归一为 audio/wav
文件字段名必须是 file
每次请求只支持上传一个文件

4. 成功响应

{
  "code": 200,
  "msg": "",
  "data": {
    "file_id": "vid_7a4b5c6d7e8f901234567890abcdef12",
    "file_kind": "video",
    "object_key": "tmp/user-1/vid_7a4b5c6d7e8f901234567890abcdef12.mp4",
    "url": "https://cdn.example.com/tmp/user-1/vid_7a4b5c6d7e8f901234567890abcdef12.mp4",
    "mime_type": "video/mp4",
    "size_bytes": 1784421,
    "expires_at": "2026-05-14T10:00:00Z"
  }
}

字段	类型	说明
`code`	number	成功时为 `200`
`msg`	string	成功时为空字符串
`data.file_id`	string	临时文件 ID。图片以 `img_` 开头，音频以 `aud_` 开头，视频以 `vid_` 开头。
`data.file_kind`	string	文件类型，可能为 `image`、`audio`、`video`
`data.object_key`	string	临时文件路径标识，通常只用于排查或记录
`data.url`	string	上传成功后的临时 HTTPS URL，可传给模型接口
`data.mime_type`	string	归一后的 MIME 类型
`data.size_bytes`	number	文件大小，单位字节
`data.expires_at`	string	预计过期时间，ISO-8601 格式

5. 错误响应

错误会以 JSON 返回。鉴权、额度、限流等错误遵循平台通用错误结构。

常见错误：

HTTP Status	示例响应	场景
`401`	`{"code":401,"msg":"API key is required","data":null}`	未传 `Authorization` 请求头
`400`	`{"code":400,"msg":"Content-Type must be multipart/form-data","data":null}`	请求类型不是 `multipart/form-data`
`400`	`{"code":400,"msg":"Field \`file` is required","data":null}`	未传 `file` 字段
`400`	`{"code":400,"msg":"Field \`file` exceeds 52428800 bytes","data":null}`	文件超过 50MB
`400`	`{"code":400,"msg":"Field \`file` must be an image, audio, or video file with a supported MIME type","data":null}`	MIME 类型不在支持范围内
`500`	`{"code":500,"msg":"File upload failed","data":null}`	上传失败，可重试；持续失败时请联系支持

6. 使用建议

上传成功后尽快使用 data.url。这是临时 URL，不适合作为长期素材地址。
上传文件时显式传正确 MIME 类型，例如 ;type=video/mp4。
如果浏览器或客户端无法提供可靠 MIME，建议先在服务端校验文件类型后再上传。
图片 URL 可按对应图片接口文档传入 input.image_urls；音频、视频 URL 请传入目标模型接口文档中说明的对应媒体字段。

文件上传接口

On this page