Risorse per sviluppatori

File e Upload

Crea, elenca, scarica ed elimina File persistenti, oppure assembla un File da parti di caricamento multiparte.

La Files API archivia file user_data, batch e batch_output immutabili con ambito Account e restituisce ID file stabili anziché URL di storage. Usa un ID file quando un’API accetta una risorsa file riutilizzabile e usa l’endpoint del contenuto quando la tua applicazione ha bisogno dei byte esatti memorizzati.

Scegli un flusso di upload

Usa POST /v1/files per creare un File da un’unica richiesta multipart. Un File user_data completato può contenere fino a 52,428,800 byte.
Usa POST /v1/files con purpose=batch per un input batch diretto fino a 95,000,000 byte.
Usa la Uploads API per inviare le Parti prima di comporre il File finale. Ogni Parte può contenere fino a 67,108,864 byte; un File user_data completato è limitato a 52,428,800 byte e un File batch completato a 209,715,200 byte. Un Upload non terminato scade dopo un’ora.
I File attivi e le prenotazioni in corso condividono un limite di archiviazione dell’Account pari a 5,368,709,120 byte.

POST /api/v1/files è un flusso di caricamento temporaneo separato che restituisce un URL temporaneo. L’SDK files.create e la CLI runapi files create continuano a utilizzare tale flusso. Utilizzare files.createFile o files.create_file, oppure la CLI runapi files create-file, quando si necessita di un oggetto File persistente.

Autenticare una richiesta

File e Upload utilizzano una Chiave API standard di RunAPI. Inviala come token Bearer:

SHELL

export RUNAPI_API_KEY="runapi_..."

Ogni File, Upload, Parte e richiesta di contenuto è limitata all’Account autenticato. Un ID di proprietà di un altro Account restituisce 404 senza rivelare se quella risorsa esiste.

Creare un File con un client compatibile

Punta un client compatibile con OpenAI all’URL base RunAPI /v1. Non sono richiesti campi di richiesta specifici di 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)

Il file restituito non contiene mai un identificatore di storage, un backend o un URL bearer.

Riferimento API

La Persistent Files API descrive l’oggetto File e le operazioni di creazione, elenco, recupero, contenuto ed eliminazione.
La Uploads API descrive l’oggetto Upload e le operazioni di creazione, aggiunta di parti, completamento e annullamento.
La Batches API descrive la creazione, lo stato, l’elenco e l’annullamento dei Moderation Batch.

Esegui la Moderazione in un Batch

Crea un File di input JSONL con una richiesta di moderazione per riga. Ogni riga utilizza la struttura Batch compatibile: custom_id, method, url impostato su /v1/moderations e un body contenente il modello di moderazione e l’input. Un File con purpose=batch può contenere fino a 50.000 richieste. La funzionalità Batch accetta attualmente l’endpoint /v1/moderations con una finestra di completamento 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"

Usa GET /v1/batches per elencare i lavori, ripeti GET /v1/batches/{batch_id} finché lo stato non è terminale, oppure chiama POST /v1/batches/{batch_id}/cancel mentre è ancora in esecuzione. I JSONL di output ed errore completati sono esposti come Files batch_output; recupera i loro metadati con GET /v1/files/{file_id} e i byte esatti con GET /v1/files/{file_id}/content.

Ciclo di vita del caricamento multiparte

Crea un Upload con il conteggio finale dei byte, il nome file, il tipo MIME e purpose=user_data. Aggiungi una o più Parti, quindi passa i loro ID a complete nell’ordine di composizione. Il completamento restituisce l’Upload con il suo File terminato.

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

Annulla un Upload non completato con POST /v1/uploads/{upload_id}/cancel. Ripetere lo stesso intento di completamento o annullamento è sicuro; un completamento, annullamento o scadenza concorrente restituisce 409 upload_state_conflict quando un altro esito terminale ha già prevalso.

Risorse CLI e SDK

La CLI espone il ciclo di vita completo:

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

Ogni Provider Client espone files e uploads. JavaScript e PHP usano createFile / deleteFile / addPart; Python e Ruby usano create_file / delete_file / add_part; Go usa CreateFile / DeleteFile / AddPart; Java usa createFile / deleteFile / addPart. List, retrieve, content, create, complete e cancel seguono la convenzione di denominazione normale di ciascun linguaggio. Consulta SDKs per l’installazione dei pacchetti.

Comportamento del ciclo di vita

Il contenuto del File è immutabile. L’eliminazione di un File lo rimuove immediatamente dagli elenchi attivi e pianifica la pulizia dello storage. Il completamento dell’Upload compone le Parti solo nell’ordine fornito, e un completamento riuscito crea un File. Mantieni l’ordine originale degli ID delle Parti quando si ritenta una risposta di completamento incerta.