コンテンツへスキップ
開発者向けリソース
開発者向けリソース

ファイルとアップロード

永続的なファイルの作成、一覧表示、ダウンロード、削除、またはマルチパートアップロードパーツからファイルを組み立てます。

Markdownを表示

Files APIは不変のアカウントスコープuser_data、batch、およびbatch_output Fileを保存し、ストレージURLの代わりに安定したFile IDを返します。再利用可能なFileリソースを受け付けるAPIではFile IDを使用し、アプリケーションが正確に保存されたバイト列を必要とする場合はコンテンツエンドポイントを使用してください。

アップロードフローを選択する

  • POST /v1/files を使用して、1つのマルチパートリクエストから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は1時間後に期限切れになります。
  • アクティブな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_..."

すべてのFile、Upload、Part、およびコンテンツリクエストは認証済みアカウントにスコープされます。別のアカウントが所有する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 リファレンス

  • Persistent Files APIは、FileオブジェクトならびにCreate・List・Retrieve・Content・Deleteの各操作について説明しています。
  • Uploads APIは、UploadオブジェクトならびにCreate・Add-part・Complete・Cancelの各操作について説明しています。
  • Batches APIは、Moderation Batchの作成・ステータス確認・一覧取得・キャンセルについて説明しています。

バッチでモデレーションを実行する

1行に1件のモデレーションリクエストを含むJSONL入力ファイルを作成します。各行は互換バッチ形式（custom_id、method、urlを/v1/moderationsに設定、モデレーションモデルと入力を含むbody）を使用します。purpose=batchファイルには最大50,000件のリクエストを含めることができます。バッチ機能は現在、24h完了ウィンドウで/v1/moderationsエンドポイントを受け付けます。

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でアップロードを作成します。1つ以上のパーツを追加し、それらの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は各言語の通常の命名規則に従います。パッケージのインストールについてはSDKsを参照してください。

ライフサイクルの動作

ファイルのコンテンツは不変です。ファイルを削除すると、アクティブなリストから直ちに削除され、ストレージのクリーンアップがスケジュールされます。アップロードの完了はパーツを指定された順序でのみ構成し、成功した完了は1つのファイルを作成します。不確かな完了レスポンスを再試行する際は、元のパーツIDの順序を維持してください。