跳到主要內容
API 參考
API 參考

建立檔案上傳

上傳一個本機檔案、遠端 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
選填

所建立分段上傳的選用檔案名稱。

sourceobject
必填

Base64 編碼的來源位元組。

source.datastring
必填

Base64 資料

source.typestring
必填

選取 base64 來源表示方式。

application/json - URL source4 個欄位
file_namestring
選填

所建立分段上傳的選用檔案名稱。

sourceobject
必填

遠端 HTTPS 來源，用於下載。

source.typestring
必填

選取 URL 來源表示方式。

source.urlstring
必填

用於下載的公開 HTTPS URL。

multipart/form-data2 個欄位
filestring
必填

要上傳的本機檔案位元組。

file_namestring
選填

所建立分段上傳的選用檔案名稱。

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 
{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

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

錯誤回應 (403)

HTTP 403
回應綱要
JSON 
{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

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

錯誤回應 (400)

HTTP 400
回應綱要
JSON 
{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

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

錯誤回應 (408)

HTTP 408
回應綱要
JSON 
{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

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

錯誤回應 (413)

HTTP 413
回應綱要
JSON 
{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

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

錯誤回應 (415)

HTTP 415
回應綱要
JSON 
{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

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

錯誤回應 (422)

HTTP 422
回應綱要
JSON 
{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

回應範例

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

錯誤回應 (429)

HTTP 429
回應綱要
JSON 
{
  "properties": {
    "error": {
      "description": "人類可讀的錯誤訊息。",
      "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"}'