Naar inhoud springen
Developer Resources
Developer Resources

Bestanden en uploads

Maak persistente bestanden aan, geef ze weer, download en verwijder ze, of stel een bestand samen uit meerdelige upload-onderdelen.

Markdown bekijken

De Files API slaat onveranderlijke, accountbrede user_data-, batch- en batch_output-bestanden op en retourneert stabiele bestand-ID’s in plaats van opslag-URL’s. Gebruik een bestand-ID wanneer een API een herbruikbare bestandsresource accepteert, en gebruik het inhoudseindpunt wanneer uw applicatie de exact opgeslagen bytes nodig heeft.

Een uploadstroom kiezen

  • Gebruik POST /v1/files om een File aan te maken vanuit één multipart-verzoek. Een voltooid user_data-bestand kan maximaal 52,428,800 bytes bevatten.
  • Gebruik POST /v1/files met purpose=batch voor een directe batchinvoer van maximaal 95,000,000 bytes.
  • Gebruik de Uploads API om Parts te verzenden voordat u het definitieve File samenstelt. Elke Part kan maximaal 67,108,864 bytes bevatten; een voltooid user_data-bestand is beperkt tot 52,428,800 bytes en een voltooid batch-bestand tot 209,715,200 bytes. Een onvoltooid Upload vervalt na één uur.
  • Actieve bestanden en lopende reserveringen delen een accountopslaglimiet van 5,368,709,120 bytes.

POST /api/v1/files is een afzonderlijke tijdelijke uploadstroom die een tijdelijke URL retourneert. SDK files.create en CLI runapi files create blijven die stroom gebruiken. Gebruik files.createFile of files.create_file, of CLI runapi files create-file, wanneer u een persistent File-object nodig hebt.

Een verzoek authenticeren

Bestanden en uploads gebruiken een standaard RunAPI API-sleutel. Stuur deze als Bearer-token:

SHELL 
export RUNAPI_API_KEY="runapi_..."

Elk bestand, elke upload, elk onderdeel en elk inhoudsverzoek heeft betrekking op het geverifieerde account. Een ID die eigendom is van een ander account geeft 404 terug zonder te onthullen of die resource bestaat.

Een bestand aanmaken met een compatibele client

Wijs een OpenAI-compatibele client naar de RunAPI /v1 basis-URL. Er zijn geen RunAPI-specifieke aanvraagvelden vereist:

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)

Het geretourneerde bestand bevat nooit een opslagidentificator, backend of bearer-URL.

API-referentie

  • Persistente Files API behandelt het File-object en de bewerkingen aanmaken, weergeven, ophalen, inhoud en verwijderen.
  • Uploads API behandelt het Upload-object en de bewerkingen aanmaken, onderdeel toevoegen, voltooien en annuleren.
  • Batches API behandelt het aanmaken, de status, het weergeven en het annuleren van Moderation Batches.

Moderatie uitvoeren in een Batch

Maak een JSONL-invoerbestand met één moderatieverzoek per regel. Elke regel gebruikt de compatibele Batch-structuur: custom_id, method, url ingesteld op /v1/moderations en een body met het moderatiemodel en de invoer. Een purpose=batch-bestand kan maximaal 50.000 verzoeken bevatten. De Batch-mogelijkheid accepteert momenteel het eindpunt /v1/moderations met een voltooiingsvenster van 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"

Gebruik GET /v1/batches om werk te bekijken, herhaal GET /v1/batches/{batch_id} totdat de status definitief is, of roep POST /v1/batches/{batch_id}/cancel aan zolang het nog actief is. Voltooide uitvoer- en fout-JSONL worden beschikbaar gesteld als batch_output Files; haal hun metagegevens op met GET /v1/files/{file_id} en de exacte bytes met GET /v1/files/{file_id}/content.

Levenscyclus van meerdelige upload

Maak een Upload aan met het definitieve aantal bytes, de bestandsnaam, het MIME-type en purpose=user_data. Voeg een of meer onderdelen toe en geef hun ID’s in samenstellingsvolgorde door aan complete. Voltooiing retourneert de Upload met het voltooide bestand.

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

Annuleer een onvoltooide Upload met POST /v1/uploads/{upload_id}/cancel. Hetzelfde voltooiingsvoornemen of dezelfde annulering herhalen is veilig; een concurrerende voltooiing, annulering of vervaldatum geeft 409 upload_state_conflict terug wanneer een andere definitieve uitkomst al heeft gewonnen.

CLI- en SDK-bronnen

De CLI stelt de volledige levenscyclus beschikbaar:

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

Elke providerclient biedt files en uploads. JavaScript en PHP gebruiken createFile / deleteFile / addPart; Python en Ruby gebruiken create_file / delete_file / add_part; Go gebruikt CreateFile / DeleteFile / AddPart; Java gebruikt createFile / deleteFile / addPart. List, retrieve, content, create, complete en cancel volgen de gebruikelijke naamgevingsconventie van elke taal. Zie SDK’s voor pakketinstallatie.

Levenscyclusgedrag

Bestandsinhoud is onveranderlijk. Het verwijderen van een bestand verwijdert het onmiddellijk uit actieve overzichten en plant opslagruiming. Uploadvoltooiing stelt onderdelen alleen samen in de opgegeven volgorde, en een geslaagde voltooiing maakt één bestand aan. Behoud de oorspronkelijke volgorde van onderdeel-ID’s bij het opnieuw proberen van een onzekere voltooiingsrespons.