跳到正文
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
响应 Schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

响应示例

JSON 
{
  "error": "Authentication required"
}
05

错误响应 (403)

HTTP 403
响应 Schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

响应示例

JSON 
{
  "error": "Standard API key required"
}
06

错误响应 (400)

HTTP 400
响应 Schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

响应示例

JSON 
{
  "error": "Only HTTPS URLs are allowed"
}
07

错误响应 (408)

HTTP 408
响应 Schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

响应示例

JSON 
{
  "error": "Download timeout"
}
08

错误响应 (413)

HTTP 413
响应 Schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

响应示例

JSON 
{
  "error": "File size exceeds the maximum allowed size"
}
09

错误响应 (415)

HTTP 415
响应 Schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

响应示例

JSON 
{
  "error": "This content type is not supported"
}
10

错误响应 (422)

HTTP 422
响应 Schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

响应示例

JSON 
{
  "error": "File upload failed. Please try again."
}
11

错误响应 (429)

HTTP 429
响应 Schema
JSON 
{
  "properties": {
    "error": {
      "description": "Human-readable error message.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

响应示例

JSON 
{
  "error": "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"}'