跳到主要內容
開發者資源
開發者資源

檔案與上傳

建立、列出、下載及刪除持久性檔案，或從分段上傳組件組合檔案。

檢視 Markdown

Files API 儲存不可變、以帳戶為範圍的 user_data、batch 及 batch_output File，並返回穩定的 File ID，而非儲存 URL。當 API 接受可重複使用的 File 資源時，請使用 File ID；當您的應用程式需要存取已儲存的原始位元組時，請使用內容端點。

選擇上傳流程

  • 使用 POST /v1/files 透過單一 multipart 請求建立 File。已完成的 user_data File 最多可包含 52,428,800 位元組。
  • 使用 POST /v1/files 並設定 purpose=batch，可直接上傳最大 95,000,000 位元組的批次輸入。
  • 使用 Uploads API 先傳送 Parts，再組合成最終的 File。每個 Part 最多可包含 67,108,864 位元組；已完成的 user_data File 上限為 52,428,800 位元組，已完成的 batch File 上限為 209,715,200 位元組。未完成的 Upload 將在一小時後過期。
  • 作用中的 Files 與進行中的預留空間共用帳戶儲存空間上限 5,368,709,120 位元組。

POST /api/v1/files 是一個獨立的暫時上傳流程，會回傳一個暫時 URL。SDK 的 files.create 和 CLI 的 runapi files create 繼續使用該流程。當您需要持久性 File 物件時，請使用 files.createFile 或 files.create_file，或 CLI 的 runapi files create-file。

對請求進行身分驗證

檔案與上傳使用標準 RunAPI API 金鑰。請以 Bearer 權杖方式傳送：

SHELL 
export RUNAPI_API_KEY="runapi_..."

每個檔案、上傳、組件及內容請求都限定於已驗證身分的帳戶。屬於其他帳戶的 ID 將回傳 404，且不會透露該資源是否存在。

使用相容用戶端建立檔案

將支援 OpenAI 的用戶端指向 RunAPI /v1 基底 URL，無需任何 RunAPI 專屬的請求欄位：

PYTHON 
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["RUNAPI_API_KEY"],
    base_url="https://runapi.ai/v1",
)

with open("knowledge.pdf", "rb") as source:
    file = client.files.create(file=source, purpose="user_data")

metadata = client.files.retrieve(file.id)
client.files.content(file.id).write_to_file("knowledge-copy.pdf")
client.files.delete(file.id)

返回的 File 絕不包含儲存識別碼、後端或持有者 URL。

API 參考

  • 持久性 Files API 涵蓋 File 物件以及建立、列出、擷取、取得內容及刪除等操作。
  • Uploads API 涵蓋 Upload 物件以及建立、新增分段、完成及取消等操作。
  • Batches API 涵蓋審核批次的建立、狀態查詢、列出及取消等操作。

以批次方式執行內容審核

建立一個 JSONL 輸入檔案，每行包含一個審核請求。每行使用相容的批次結構：custom_id、method、url 設為 /v1/moderations，以及包含審核模型與輸入內容的 body。purpose=batch 的檔案最多可包含 50,000 個請求。批次功能目前接受 /v1/moderations 端點，完成時間窗口為 24h。

SHELL 
INPUT_FILE_ID=$(curl -sS https://runapi.ai/v1/files \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -F purpose=batch \
  -F [email protected] | jq -r .id)

BATCH_ID=$(curl -sS https://runapi.ai/v1/batches \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg file "$INPUT_FILE_ID" '{input_file_id:$file,endpoint:"/v1/moderations",completion_window:"24h"}')" \
  | jq -r .id)

curl -sS "https://runapi.ai/v1/batches/$BATCH_ID" \
  -H "Authorization: Bearer $RUNAPI_API_KEY"

使用 GET /v1/batches 列出工作項目，重複呼叫 GET /v1/batches/{batch_id} 直到狀態進入終止狀態，或在仍執行中時呼叫 POST /v1/batches/{batch_id}/cancel。完成的輸出與錯誤 JSONL 會以 batch_output Files 形式公開；使用 GET /v1/files/{file_id} 取得其中繼資料，並使用 GET /v1/files/{file_id}/content 取得確切的位元組內容。

分段上傳生命週期

使用最終位元組數、檔案名稱、MIME 類型及 purpose=user_data 建立上傳。新增一個或多個部分，然後按組合順序將其 ID 傳遞至 complete。完成後返回包含已完成檔案的上傳物件。

SHELL 
UPLOAD_ID=$(curl -sS https://runapi.ai/v1/uploads \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bytes":1048576,"filename":"archive.bin","mime_type":"application/octet-stream","purpose":"user_data"}' \
  | jq -r .id)

PART_ID=$(curl -sS "https://runapi.ai/v1/uploads/$UPLOAD_ID/parts" \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -F [email protected] | jq -r .id)

curl -sS "https://runapi.ai/v1/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"part_ids\":[\"$PART_ID\"]}"

使用 POST /v1/uploads/{upload_id}/cancel 取消未完成的上傳。重複相同的完成意圖或取消操作是安全的；若另一個終態結果已先確定，則競爭的完成、取消或過期操作將返回 409 upload_state_conflict。

CLI 與 SDK 資源

CLI 提供完整的生命週期操作：

SHELL 
runapi files create-file knowledge.pdf
runapi files list --order desc
runapi files retrieve file_123
runapi files content file_123 --output knowledge-copy.pdf
runapi files delete file_123

runapi uploads create --bytes 1048576 --filename archive.bin --mime-type application/octet-stream
runapi uploads add-part upload_123 archive.part-01
runapi uploads complete upload_123 --part-id part_123
runapi uploads cancel upload_123

每個 Provider Client 皆公開 files 與 uploads。JavaScript 和 PHP 使用 createFile / deleteFile / addPart；Python 和 Ruby 使用 create_file / delete_file / add_part；Go 使用 CreateFile / DeleteFile / AddPart；Java 使用 createFile / deleteFile / addPart。List、retrieve、content、create、complete 及 cancel 遵循 各語言的一般命名慣例。請參閱 SDK以了解套件安裝方式。

生命週期行為

檔案內容不可變更。刪除檔案會立即將其從活躍列表中移除，並排程儲存空間清理。上傳完成時僅依提供的順序組合組件，且成功完成後會建立一個檔案。在重試不確定的完成回應時，請保持原始組件 ID 的順序。