开发者资源

Files 与 Uploads

创建、列出、下载和删除持久 File，或通过多个 Upload Part 组装 File。

Files API 保存不可变、按 Account 隔离的 user_data、batch 和 batch_output File，并返回稳定的 File ID，而不是存储 URL。当 API 接受可复用 File resource 时传入 File ID；应用需要原始内容时，通过 content endpoint 读取完全一致的字节。

选择上传流程

使用 POST /v1/files 通过一次 multipart 请求创建 File。完成后的 user_data File 最大为 52,428,800 bytes。
使用 POST /v1/files 并设置 purpose=batch，直接创建最大 95,000,000 bytes 的 Batch 输入 File。
使用 Uploads API 先发送多个 Part，再组装最终 File。每个 Part 最大为 67,108,864 bytes；完成后的 user_data File 最大为 52,428,800 bytes，batch File 最大为 209,715,200 bytes；未完成的 Upload 会在一小时后过期。
Active File 和进行中的 reservation 共用 Account 存储上限 5,368,709,120 bytes。

POST /api/v1/files 是独立的临时上传流程，返回临时 URL。SDK files.create 与 CLI runapi files create 会继续使用该流程。需要持久 File object 时，请使用 files.createFile 或 files.create_file，或者 CLI runapi files create-file。

认证请求

Files 与 Uploads 使用标准 RunAPI API Key。请通过 Bearer token 发送：

SHELL

export RUNAPI_API_KEY="runapi_..."

每个 File、Upload、Part 和 content 请求都按当前认证 Account 隔离。访问其他 Account 拥有的 ID 会返回 404，且不会泄露该 resource 是否存在。

使用兼容客户端创建 File

将 OpenAI-compatible client 指向 RunAPI /v1 base 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 不会包含 storage identifier、backend 或 bearer URL。

API Reference

Persistent Files API 包含 File 对象及 create、list、retrieve、content 和 delete operation。
Uploads API 包含 Upload 对象及 create、add-part、complete 和 cancel operation。
Batches API 包含 Moderation Batch 的创建、状态查询、列表和取消 operation。

批量执行 Moderation

创建 JSONL 输入 File，每行包含一个 moderation request。每行使用兼容 Batch 格式：custom_id、method、值为 /v1/moderations 的 url，以及包含 moderation model 和 input 的 body。purpose=batch File 最多包含 50,000 个 request。当前 Batch capability 只接受 /v1/moderations endpoint 和 24h completion window。

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 列出 Batch，重复 GET /v1/batches/{batch_id} 直到状态进入终态；仍在运行时可调用 POST /v1/batches/{batch_id}/cancel。完成后的 output 和 error JSONL 会作为 batch_output File 提供；使用 GET /v1/files/{file_id} 获取 metadata，使用 GET /v1/files/{file_id}/content 读取完整 bytes。

Multipart Upload 生命周期

创建 Upload 时提供最终 byte count、filename、MIME type 和 purpose=user_data。添加一个或多个 Part 后，按组装顺序将 Part ID 传给 complete。完成后会返回包含最终 File 的 Upload。

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 取消未完成的 Upload。相同 complete intent 或 cancel 可安全重试；当 complete、cancel 或 expiry 竞争且另一个终态已经胜出时，返回 409 upload_state_conflict。

CLI 与 SDK resource

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。

生命周期行为

File content 不可变。删除 File 后，它会立即从 active list 中消失，并调度 storage cleanup。Upload complete 只按提供的顺序组装 Part；一次成功 complete 只创建一个 File。若 complete response 不确定，重试时请保持原有 Part ID 顺序。