File Upload API

Use POST https://file.reachapi.ai/file/uploads to upload a local image, audio, or video file before calling a model API that requires a reachable file URL. The response returns a temporary HTTPS URL in data.url.

This endpoint is useful when your source file is on a local device or in a private environment. If you already have a public HTTPS file URL that the target model accepts, you can pass that URL directly without uploading it first.

1. Endpoint

Item	Value
Method	`POST`
URL	`https://file.reachapi.ai/file/uploads`
Authentication	`Authorization: Bearer YOUR_REACH_API_KEY`
Request type	`multipart/form-data`
File field	`file`
Upload mode	Single file
Size limit	`52428800` bytes, about `50MB`

Request headers:

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

When using curl, SDK upload helpers, or FormData, let the client generate the multipart boundary.

2. Request

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 Fields

Field	Type	Required	Description
`file`	binary	Yes	Local image, audio, or video file to upload. No extra file-type field is required.

3. Supported File Types

File kind	Supported MIME types	Returned `file_kind`
Image	`image/png`, `image/jpeg`, `image/jpg`, `image/webp`, `image/gif`	`image`
Audio	`audio/mpeg`, `audio/mp3`, `audio/wav`, `audio/x-wav`, `audio/mp4`, `audio/aac`, `audio/ogg`, `audio/webm`	`audio`
Video	`video/mp4`, `video/webm`, `video/quicktime`, `video/x-matroska`	`video`

Notes:

image/jpg is normalized to image/jpeg
audio/mp3 is normalized to audio/mpeg
audio/x-wav is normalized to audio/wav
The form field name must be file
Only one file can be uploaded per request

4. Success Response

{
  "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"
  }
}

Field	Type	Description
`code`	number	`200` when the upload succeeds
`msg`	string	Empty string when the upload succeeds
`data.file_id`	string	Temporary file ID. Image IDs start with `img_`, audio IDs with `aud_`, and video IDs with `vid_`.
`data.file_kind`	string	File kind: `image`, `audio`, or `video`
`data.object_key`	string	Temporary file path identifier returned for tracing or support
`data.url`	string	Temporary HTTPS URL to pass to model APIs
`data.mime_type`	string	Normalized MIME type
`data.size_bytes`	number	File size in bytes
`data.expires_at`	string	Estimated expiration time in ISO-8601 format

5. Errors

Errors are returned as JSON. Authentication, quota, and rate-limit errors follow the platform-wide error contract.

Common examples:

HTTP Status	Example response	Scenario
`401`	`{"code":401,"msg":"API key is required","data":null}`	Missing `Authorization` header
`400`	`{"code":400,"msg":"Content-Type must be multipart/form-data","data":null}`	Request is not `multipart/form-data`
`400`	`{"code":400,"msg":"Field \`file` is required","data":null}`	Missing `file` field
`400`	`{"code":400,"msg":"Field \`file` exceeds 52428800 bytes","data":null}`	File is larger than 50MB
`400`	`{"code":400,"msg":"Field \`file` must be an image, audio, or video file with a supported MIME type","data":null}`	Unsupported MIME type
`500`	`{"code":500,"msg":"File upload failed","data":null}`	Upload failed; retry or contact support if it continues

6. Usage Tips

Use data.url soon after upload. It is a temporary URL, not permanent storage.
Send the correct MIME type when uploading, for example ;type=video/mp4.
If a browser or client cannot provide a reliable MIME type, validate the file type on your server before uploading.
Pass image URLs to image APIs through fields such as input.image_urls, and pass audio or video URLs to the corresponding media fields documented by each model API.

File Upload API

On this page