文件上傳接口

使用 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