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

檔案與上傳

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

檢視 Markdown

Files API 儲存不可變的、帳戶範疇的 user_data、batch 及 batch_output 檔案，並返回穩定的 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 在組合最終 File 之前先發送各個 Part。每個 Part 最多可包含 67,108,864 位元組；已完成的 user_data File 上限為 52,428,800 位元組，已完成的 batch File 上限為 209,715,200 位元組。未完成的 Upload 將在一小時後過期。
  • 已啟用的 File 與進行中的預留共用帳戶儲存空間上限，為 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 涵蓋 Moderation Batch 的建立、狀態查詢、列出與取消。

批次執行審核

建立一個每行包含一個審核請求的 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。列出、擷取、內容、建立、完成及取消均遵循各語言的一般命名慣例。有關套件安裝，請參閱 SDKs。

生命週期行為

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