Skip to content
RunAPI Developer Docs
EN 中文
API Reference
API Reference

Create a File Upload

Upload one local file, remote HTTPS URL, or base64 source and receive a temporary URL.

View Markdown

Upload one local file, remote HTTPS URL, or base64 source and receive a temporary URL.

Endpoint

POST /api/v1/files
Base URL
https://runapi.ai
API version
v1
Authentication
Authorization: Bearer YOUR_API_KEY
02

Request

JSON body

Send values only in the listed request location.

application/json - Base64 source4 fields
file_namestring
Optional

Optional filename for the created File Upload.

sourceobject
Required

Base64-encoded source bytes.

source.datastring
Required

Base64 data

source.typestring
Required

Selects the base64 source representation.

application/json - URL source4 fields
file_namestring
Optional

Optional filename for the created File Upload.

sourceobject
Required

Remote HTTPS source to download.

source.typestring
Required

Selects the URL source representation.

source.urlstring
Required

Public HTTPS URL to download.

multipart/form-data2 fields
filestring
Required

Local file bytes to upload.

file_namestring
Optional

Optional filename for the created File Upload.

03

Success response

HTTP 201

POST /api/v1/files

JSON 
{
  "created_at": "2026-07-27T10:00:00.000Z",
  "expires_at": "2026-07-27T11:00:00.000Z",
  "file_name": "mask.png",
  "mime_type": "image/png",
  "size_bytes": 204800,
  "url": "https://file.runapi.ai/temp/user-uploads/mask.png"
}
04

Error response (401)

HTTP 401
JSON 
{
  "error": {
    "code": "authentication_required",
    "message": "Authentication required"
  }
}
05

Error response (403)

HTTP 403
JSON 
{
  "error": {
    "code": "standard_api_key_required",
    "message": "Standard API key required"
  }
}
06

Error response (400)

HTTP 400
JSON 
{
  "error": {
    "code": "invalid_source",
    "message": "Only HTTPS URLs are allowed"
  }
}
07

Error response (408)

HTTP 408
JSON 
{
  "error": {
    "code": "invalid_source",
    "message": "Download timeout"
  }
}
08

Error response (413)

HTTP 413
JSON 
{
  "error": {
    "code": "file_too_large",
    "message": "File size exceeds the maximum allowed size"
  }
}
09

Error response (415)

HTTP 415
JSON 
{
  "error": {
    "code": "unsupported_media_type",
    "message": "This content type is not supported"
  }
}
10

Error response (422)

HTTP 422
JSON 
{
  "error": {
    "code": "upload_failed",
    "message": "File upload failed. Please try again."
  }
}
11

Error response (429)

HTTP 429
JSON 
{
  "error": {
    "code": "rate_limited",
    "message": "Too many file uploads for this account. Please retry later."
  }
}
12

cURL example

CURL 
curl -X POST https://runapi.ai/api/v1/files \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"source":{"type":"url","url":"https://cdn.runapi.ai/public/samples/mask.png"},"file_name":"mask.png"}'