Recursos para desarrolladores

Files y Uploads

Cree, liste, descargue y elimine Files persistentes, o ensamble un File a partir de partes de carga multiparte.

La API de archivos almacena archivos user_data, batch y batch_output inmutables con alcance de cuenta, y devuelve IDs de archivo estables en lugar de URLs de almacenamiento. Usa un ID de archivo cuando una API acepte un recurso File reutilizable, y usa el endpoint de contenido cuando tu aplicación necesite los bytes exactos almacenados.

Elegir un flujo de Upload

Use POST /v1/files para crear un archivo a partir de una única solicitud multiparte. Un archivo user_data completado puede contener hasta 52,428,800 bytes.
Use POST /v1/files con purpose=batch para una entrada de lote directa de hasta 95,000,000 bytes.
Use la API de Uploads para enviar partes antes de componer el archivo final. Cada parte puede contener hasta 67,108,864 bytes; un archivo user_data completado está limitado a 52,428,800 bytes y un archivo batch completado a 209,715,200 bytes. Una carga no finalizada expira después de una hora.
Los archivos activos y las reservas en curso comparten un límite de almacenamiento de cuenta de 5,368,709,120 bytes.

POST /api/v1/files es un flujo de carga temporal independiente que devuelve una URL temporal. SDK files.create y CLI runapi files create continúan usando ese flujo. Usa files.createFile o files.create_file, o CLI runapi files create-file, cuando necesites un objeto File persistente.

Autenticar una solicitud

Files y Uploads utilizan una clave de API estándar de RunAPI. Envíela como token Bearer:

SHELL

export RUNAPI_API_KEY="runapi_..."

Cada solicitud de File, Upload, Part y contenido está limitada a la cuenta autenticada. Un ID perteneciente a otra cuenta devuelve 404 sin revelar si ese recurso existe.

Crear un File con un cliente compatible

Apunte un cliente compatible con OpenAI a la URL base /v1 de RunAPI. No se requieren campos de solicitud específicos de 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)

El archivo devuelto nunca contiene un identificador de almacenamiento, un backend ni una URL de portador.

Referencia de la API

La API de archivos persistentes cubre el objeto File y las operaciones de creación, listado, recuperación, contenido y eliminación.
La API de Uploads cubre el objeto Upload y las operaciones de creación, adición de parte, finalización y cancelación.
La API de Batches cubre la creación, el estado, el listado y la cancelación de lotes de moderación.

Ejecutar Moderación en un Batch

Cree un File JSONL de entrada con una solicitud de moderación por línea. Cada línea utiliza la forma de Batch compatible: custom_id, method, url establecida en /v1/moderations, y un body que contiene el modelo de moderación y la entrada. Un File con purpose=batch puede contener hasta 50.000 solicitudes. La capacidad de Batch acepta actualmente el endpoint /v1/moderations con una ventana de finalización 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"

Usa GET /v1/batches para listar el trabajo, repite GET /v1/batches/{batch_id} hasta que el estado sea terminal, o llama a POST /v1/batches/{batch_id}/cancel mientras aún esté en ejecución. La salida completada y el JSONL de errores se exponen como Files batch_output; recupera sus metadatos con GET /v1/files/{file_id} y los bytes exactos con GET /v1/files/{file_id}/content.

Ciclo de vida de carga multiparte

Cree un Upload con el recuento final de bytes, el nombre de archivo, el tipo MIME y purpose=user_data. Añada una o más partes y pase sus IDs a complete en el orden de composición. La finalización devuelve el Upload con su File terminado.

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

Cancele un Upload sin terminar con POST /v1/uploads/{upload_id}/cancel. Repetir la misma intención de finalización o cancelación es seguro; una finalización, cancelación o vencimiento en competencia devuelve 409 upload_state_conflict cuando otro resultado terminal ya ha prevalecido.

Recursos de CLI y SDK

La CLI expone el ciclo de vida 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

Cada cliente de proveedor expone files y uploads. JavaScript y PHP usan createFile / deleteFile / addPart; Python y Ruby usan create_file / delete_file / add_part; Go usa CreateFile / DeleteFile / AddPart; Java usa createFile / deleteFile / addPart. List, retrieve, content, create, complete y cancel siguen la convención de nombres habitual de cada lenguaje. Consulte SDKs para la instalación de paquetes.

Comportamiento del ciclo de vida

El contenido de un File es inmutable. Eliminar un File lo retira de los listados activos de inmediato y programa la limpieza del almacenamiento. La finalización de la carga combina las partes únicamente en el orden indicado, y una finalización exitosa crea un único File. Conserve el orden original de los IDs de parte al reintentar una respuesta de finalización incierta.