跳到正文
RunAPI 开发者文档
EN 中文
API 参考
API 参考

创建 File Upload

上传一个本地文件、远程 HTTPS URL 或 base64 来源，并获得临时 URL。

查看 Markdown

上传一个本地文件、远程 HTTPS URL 或 base64 来源，并获得临时 URL。

端点

POST /api/v1/files
基础 URL
https://runapi.ai
API 版本
v1
身份验证
Authorization: Bearer YOUR_API_KEY
02

请求

JSON 请求体

只能在列出的请求位置发送值。

application/json - Base64 source4 个字段
file_namestring
可选

Optional filename for the created File Upload.

sourceobject
必填

Base64-encoded source bytes.

source.datastring
必填

Base64 data

source.typestring
必填

Selects the base64 source representation.

application/json - URL source4 个字段
file_namestring
可选

Optional filename for the created File Upload.

sourceobject
必填

Remote HTTPS source to download.

source.typestring
必填

Selects the URL source representation.

source.urlstring
必填

Public HTTPS URL to download.

multipart/form-data2 个字段
filestring
必填

Local file bytes to upload.

file_namestring
可选

Optional filename for the created File Upload.

03

成功响应

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

错误响应 (401)

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

错误响应 (403)

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

错误响应 (400)

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

错误响应 (408)

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

错误响应 (413)

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

错误响应 (415)

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

错误响应 (422)

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

错误响应 (429)

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

cURL 示例

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"}'
13

相关参考