Zum Inhalt springen
Entwickler-Ressourcen
Entwickler-Ressourcen

Dateien und Uploads

Erstellen, auflisten, herunterladen und löschen Sie persistente Dateien oder assemblieren Sie eine Datei aus mehrteiligen Upload-Teilen.

Markdown anzeigen

Die Files API speichert unveränderliche, kontobezogene user_data-, batch- und batch_output-Files und gibt stabile File-IDs anstelle von Speicher-URLs zurück. Verwenden Sie eine File-ID, wenn eine API eine wiederverwendbare File-Ressource akzeptiert, und verwenden Sie den Content-Endpunkt, wenn Ihre Anwendung die exakten gespeicherten Bytes benötigt.

Einen Upload-Ablauf auswählen

  • Verwenden Sie POST /v1/files, um eine Datei aus einer einzelnen Multipart-Anfrage zu erstellen. Eine abgeschlossene user_data-Datei kann bis zu 52,428,800 Bytes enthalten.
  • Verwenden Sie POST /v1/files mit purpose=batch für eine direkte Batch-Eingabe von bis zu 95,000,000 Bytes.
  • Verwenden Sie die Uploads API, um Teile zu senden, bevor Sie die endgültige Datei zusammenstellen. Jeder Teil kann bis zu 67,108,864 Bytes enthalten; eine abgeschlossene user_data-Datei ist auf 52,428,800 Bytes und eine abgeschlossene batch-Datei auf 209,715,200 Bytes begrenzt. Ein unvollendeter Upload läuft nach einer Stunde ab.
  • Aktive Dateien und laufende Reservierungen teilen sich ein Kontospeicherlimit von 5,368,709,120 Bytes.

POST /api/v1/files ist ein separater temporärer Upload-Ablauf, der eine temporäre URL zurückgibt. Das SDK files.create und die CLI runapi files create verwenden weiterhin diesen Ablauf. Verwenden Sie files.createFile oder files.create_file, bzw. die CLI runapi files create-file, wenn Sie ein dauerhaftes File-Objekt benötigen.

Eine Anfrage authentifizieren

Dateien und Uploads verwenden einen Standard-RunAPI-API-Schlüssel. Senden Sie ihn als Bearer-Token:

SHELL 
export RUNAPI_API_KEY="runapi_..."

Jede Datei-, Upload-, Part- und Inhaltsanfrage ist auf das authentifizierte Konto beschränkt. Eine ID, die einem anderen Konto gehört, gibt 404 zurück, ohne preiszugeben, ob diese Ressource existiert.

Eine File mit einem kompatiblen Client erstellen

Richten Sie einen OpenAI-kompatiblen Client auf die RunAPI-Basis-URL /v1 aus. Es sind keine RunAPI-spezifischen Anforderungsfelder erforderlich:

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)

Der zurückgegebene File enthält niemals eine Speicherkennung, ein Backend oder eine Bearer-URL.

API-Referenz

  • Persistent Files API behandelt das File-Objekt sowie die Operationen Erstellen, Auflisten, Abrufen, Inhalt und Löschen.
  • Uploads API behandelt das Upload-Objekt sowie die Operationen Erstellen, Teil hinzufügen, Abschließen und Abbrechen.
  • Batches API behandelt die Erstellung, den Status, die Auflistung und den Abbruch von Moderation-Batches.

Moderation in einem Batch ausführen

Erstellen Sie eine JSONL-Eingabe-File mit einer Moderationsanfrage pro Zeile. Jede Zeile verwendet die kompatible Batch-Form: custom_id, method, url auf /v1/moderations gesetzt und einen body mit dem Moderationsmodell und der Eingabe. Eine purpose=batch-File kann bis zu 50.000 Anfragen enthalten. Die Batch-Funktion akzeptiert derzeit den /v1/moderations-Endpunkt mit einem 24h-Abschlussfenster.

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"

Verwende GET /v1/batches, um Aufgaben aufzulisten, wiederhole GET /v1/batches/{batch_id} bis der Status terminal ist, oder rufe POST /v1/batches/{batch_id}/cancel auf, solange er noch läuft. Abgeschlossene Ausgabe- und Fehler-JSONL sind als batch_output-Files verfügbar; rufe ihre Metadaten mit GET /v1/files/{file_id} und die genauen Bytes mit GET /v1/files/{file_id}/content ab.

Lebenszyklus von Multipart-Uploads

Erstellen Sie einen Upload mit der endgültigen Byte-Anzahl, dem Dateinamen, dem MIME-Typ und purpose=user_data. Fügen Sie einen oder mehrere Parts hinzu und übergeben Sie deren IDs in der Zusammensetzungsreihenfolge an complete. Der Abschluss gibt den Upload mit seiner fertigen File zurück.

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\"]}"

Brechen Sie einen unvollständigen Upload mit POST /v1/uploads/{upload_id}/cancel ab. Das wiederholte Senden derselben Abschlussabsicht oder Stornierung ist sicher; ein konkurrierender Abschluss, eine Stornierung oder ein Ablauf gibt 409 upload_state_conflict zurück, wenn ein anderes terminales Ergebnis bereits eingetreten ist.

CLI- und SDK-Ressourcen

Die CLI stellt den vollständigen Lebenszyklus bereit:

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

Jeder Provider-Client stellt files und uploads bereit. JavaScript und PHP verwenden createFile / deleteFile / addPart; Python und Ruby verwenden create_file / delete_file / add_part; Go verwendet CreateFile / DeleteFile / AddPart; Java verwendet createFile / deleteFile / addPart. Auflisten, Abrufen, Inhalt, Erstellen, Abschließen und Abbrechen folgen der üblichen Namenskonvention der jeweiligen Sprache. Informationen zur Paketinstallation finden Sie unter SDKs.

Lebenszyklusverhalten

Dateiinhalte sind unveränderlich. Das Löschen einer Datei entfernt sie sofort aus aktiven Auflistungen und plant die Speicherbereinigung. Der Upload-Abschluss setzt Parts nur in der angegebenen Reihenfolge zusammen, und ein erfolgreicher Abschluss erstellt eine Datei. Behalten Sie die ursprüngliche Part-ID-Reihenfolge bei, wenn Sie eine unsichere Abschlussantwort wiederholen.