Ressources pour développeurs

Fichiers et téléchargements

Créez, listez, téléchargez et supprimez des fichiers persistants, ou assemblez un fichier à partir de parties de téléchargement multipart.

Voir en Markdown

L’API Files stocke des Files immuables, limités au périmètre du compte, de types user_data, batch et batch_output, et retourne des identifiants de File stables au lieu d’URL de stockage. Utilisez un identifiant de File lorsqu’une API accepte une ressource File réutilisable, et utilisez l’endpoint de contenu lorsque votre application a besoin des octets exacts stockés.

Choisir un flux d'upload

Utilisez POST /v1/files pour créer un File à partir d’une seule requête multipart. Un File user_data complété peut contenir jusqu’à 52,428,800 octets.
Utilisez POST /v1/files avec purpose=batch pour une entrée batch directe allant jusqu’à 95,000,000 octets.
Utilisez l’Uploads API pour envoyer des Parts avant de composer le File final. Chaque Part peut contenir jusqu’à 67,108,864 octets ; un File user_data complété est limité à 52,428,800 octets et un File batch complété à 209,715,200 octets. Un Upload inachevé expire après une heure.
Les Files actifs et les réservations en cours partagent une limite de stockage de compte de 5,368,709,120 octets.

POST /api/v1/files est un flux d’importation temporaire distinct qui retourne une URL temporaire. Le SDK files.create et le CLI runapi files create continuent d’utiliser ce flux. Utilisez files.createFile ou files.create_file, ou le CLI runapi files create-file, lorsque vous avez besoin d’un objet File persistant.

Authentifier une requête

Les fichiers et téléchargements utilisent une clé API RunAPI standard. Envoyez-la en tant que jeton Bearer :

SHELL

export RUNAPI_API_KEY="runapi_..."

Chaque requête de fichier, de téléchargement, de partie et de contenu est limitée au compte authentifié. Un identifiant appartenant à un autre compte renvoie 404 sans révéler si cette ressource existe.

Créer un File avec un client compatible

Pointez un client compatible OpenAI vers l’URL de base RunAPI /v1. Aucun champ de requête spécifique à RunAPI n’est requis :

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)

Le File retourné ne contient jamais d’identifiant de stockage, de backend ni d’URL porteuse.

Référence API

L’API Persistent Files couvre l’objet File ainsi que les opérations de création, listage, récupération, contenu et suppression.
L’API Uploads couvre l’objet Upload et les opérations de création, ajout de partie, finalisation et annulation.
L’API Batches couvre la création, le statut, le listage et l’annulation des Moderation Batch.

Exécuter une modération dans un Batch

Créez un File d’entrée JSONL avec une requête de modération par ligne. Chaque ligne utilise la forme Batch compatible : custom_id, method, url défini à /v1/moderations, et un body contenant le modèle de modération et l’entrée. Un File purpose=batch peut contenir jusqu’à 50 000 requêtes. La capacité Batch accepte actuellement l’endpoint /v1/moderations avec une fenêtre de complétion de 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"

Utilisez GET /v1/batches pour lister les travaux, répétez GET /v1/batches/{batch_id} jusqu’à ce que le statut soit terminal, ou appelez POST /v1/batches/{batch_id}/cancel tant qu’il est encore en cours d’exécution. Les fichiers JSONL de sortie et d’erreur complétés sont exposés en tant que Files batch_output ; récupérez leurs métadonnées avec GET /v1/files/{file_id} et les octets exacts avec GET /v1/files/{file_id}/content.

Cycle de vie du téléversement multipartite

Créez un Upload avec le nombre d’octets final, le nom de fichier, le type MIME et purpose=user_data. Ajoutez une ou plusieurs Parts, puis transmettez leurs ID à complete dans l’ordre de composition. La finalisation retourne l’Upload avec son File terminé.

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

Annulez un Upload non terminé avec POST /v1/uploads/{upload_id}/cancel. Répéter la même intention de finalisation ou d’annulation est sans danger ; une finalisation, annulation ou expiration concurrente retourne 409 upload_state_conflict lorsqu’un autre résultat terminal a déjà prévalu.

Ressources CLI et SDK

La CLI expose le cycle de vie complet :

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

Chaque client fournisseur expose files et uploads. JavaScript et PHP utilisent createFile / deleteFile / addPart ; Python et Ruby utilisent create_file / delete_file / add_part ; Go utilise CreateFile / DeleteFile / AddPart ; Java utilise createFile / deleteFile / addPart. List, retrieve, content, create, complete et cancel suivent la convention de nommage normale de chaque langage. Consultez les SDK pour l’installation des packages.

Comportement du cycle de vie

Le contenu d’un fichier est immuable. La suppression d’un fichier le retire immédiatement des listes actives et planifie le nettoyage du stockage. La finalisation du téléchargement compose les parties uniquement dans l’ordre fourni, et une finalisation réussie crée un seul fichier. Conservez l’ordre d’origine des identifiants de partie lors de la nouvelle tentative d’une réponse de finalisation incertaine.