Guías
Carga de archivos
Sube un archivo una vez y haz referencia a él por su ID en las solicitudes de Messages, Responses, generación de imágenes y generación de vídeos.
Sube un archivo una vez y luego haz referencia a él por su ID en las solicitudes a modelos. Esto sustituye a reenviar los mismos bytes en base64 o a alojar el archivo en una URL pública.
Un ID de archivo funciona con Messages, Responses, la generación de imágenes y la generación de video. No funciona con Chat Completions.
Antes de empezar
- Una clave de API. Consulta Autenticación.
- La URL base
https://openapi.felo.ai. - Un modelo que acepte el tipo de archivo que vas a enviar. Consulta Comprobar la compatibilidad del modelo.
Inicio rápido
1. Subir el archivo
curl "https://openapi.felo.ai/api/v1/files" \
-H "Authorization: Bearer ${FELO_API_KEY}" \
-F "file=@./report.pdf"Una carga correcta devuelve HTTP 200 con los metadatos del archivo:
{
"id": "felo_file_0179...",
"type": "file",
"source": "upload",
"filename": "report.pdf",
"mime_type": "application/pdf",
"size_bytes": 482113,
"created_at": "2026-11-10T02:25:41Z",
"downloadable": false
}Guarda id. Trátalo como una cadena opaca: no lo construyas ni lo analices.
2. Referenciarlo en una solicitud
curl "https://openapi.felo.ai/api/v1/responses" \
-H "Authorization: Bearer ${FELO_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": [
{
"role": "user",
"content": [
{"type": "input_file", "file_id": "felo_file_0179..."},
{"type": "input_text", "text": "Summarize the attached report."}
]
}
]
}'Los mismos dos pasos en Python:
import os
import requests
BASE = "https://openapi.felo.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['FELO_API_KEY']}"}
def upload(path: str) -> str:
with open(path, "rb") as file:
response = requests.post(
f"{BASE}/api/v1/files",
headers=HEADERS,
files={"file": file},
timeout=300,
)
response.raise_for_status()
return response.json()["id"]
file_id = upload("./report.pdf")
response = requests.post(
f"{BASE}/api/v1/responses",
headers=HEADERS,
json={
"model": "gpt-5.5",
"input": [
{
"role": "user",
"content": [
{"type": "input_file", "file_id": file_id},
{"type": "input_text", "text": "Summarize the attached report."},
],
}
],
},
timeout=120,
)
response.raise_for_status()
print(response.json())Y en Node.js 20 o posterior:
import { openAsBlob } from "node:fs";
import { basename } from "node:path";
const BASE = "https://openapi.felo.ai";
const headers = { Authorization: `Bearer ${process.env.FELO_API_KEY}` };
async function upload(path) {
const form = new FormData();
form.append("file", await openAsBlob(path), basename(path));
const response = await fetch(`${BASE}/api/v1/files`, { method: "POST", headers, body: form });
if (!response.ok) throw new Error(`Upload failed: ${response.status} ${await response.text()}`);
return (await response.json()).id;
}
const fileId = await upload("./report.pdf");Reglas de carga
- El cuerpo es
multipart/form-datacon exactamente una parte, llamadafile. Cualquier otra parte, incluidapurpose, se rechaza coninvalid_file. - Deja que tu cliente HTTP establezca
Content-Type. Si lo defines a mano, se pierde el multipart boundary. - No añadas parámetros de consulta a la URL de carga.
- Sube por HTTP en lugar de usar el helper Files de un SDK.
files.create()del SDK de OpenAI siempre envíapurpose, por lo que no puede llamar a este endpoint. - Una carga que agota el tiempo de espera o se desconecta puede haberse almacenado de todos modos. Lista tus archivos antes de volver a subir.
Dónde se puede usar un ID de archivo
| Endpoint | Tipos de archivo | Modalidad de entrada requerida | Campo |
|---|---|---|---|
POST /api/v1/messages | PDF, imagen | file, image | messages[].content[] |
POST /api/v1/responses | PDF, imagen | file, image | input[].content[] |
POST /api/v1/images/generations | Imagen | image | input_references[] |
POST /api/v1/videos/generations | Imagen | image | frame_images[] |
POST /api/v1/videos/generations | Imagen, MP4, audio | image, video, audio | input_references[] |
POST /api/v1/chat/completions | No admitido |
Messages
{
"model": "claude-haiku-4-5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{"type": "document", "source": {"type": "file", "file_id": "felo_file_0179..."}},
{"type": "text", "text": "Summarize the attached report."}
]
}
]
}Para una imagen, usa {"type": "image", "source": {"type": "file", "file_id": "..."}}.
Responses
| Archivo | Bloque de contenido |
|---|---|
{"type": "input_file", "file_id": "..."} | |
| Imagen | {"type": "input_image", "file_id": "...", "detail": "auto"} |
Un bloque que lleva file_id no debe llevar además una URL ni datos en base64.
Generación de imágenes
{
"model": "gemini-3-pro-image",
"prompt": "Keep the product and framing. Replace the background with a sunlit marble countertop.",
"input_references": [
{"type": "image_url", "image_url": {"file_id": "felo_file_0179..."}}
]
}El resto de la solicitud, la respuesta 202 y la consulta de la tarea se describen en Generación de imágenes.
Generación de video
Los fotogramas inicial y final van en frame_images:
{
"model": "YOUR_VIDEO_MODEL",
"prompt": "The camera slowly pushes in. Keep the colors and composition.",
"duration": 5,
"resolution": "720p",
"frame_images": [
{
"type": "image_url",
"frame_type": "first_frame",
"image_url": {"file_id": "felo_file_0179..."}
}
]
}Añade una segunda entrada con "frame_type": "last_frame" para un fotograma final. Un fotograma final requiere un fotograma inicial.
El material de referencia va en input_references. Cada entrada usa el localizador que corresponde a su tipo de medio:
{
"input_references": [
{"type": "image_url", "image_url": {"file_id": "felo_file_IMAGE"}},
{"type": "video_url", "video_url": {"file_id": "felo_file_VIDEO"}},
{"type": "audio_url", "audio_url": {"file_id": "felo_file_AUDIO"}}
]
}Las combinaciones que acepta un modelo dependen del modelo y del canal. frame_images e input_references no se pueden usar en la misma solicitud.
Reglas de los localizadores
- En las solicitudes de imagen y de video, cada objeto
image_url,video_urloaudio_urlcontiene exactamente uno de los camposfile_idourl, y ningún otro. - Un mismo array puede mezclar entradas que usan
file_idcon entradas que usanurl. - La generación de imágenes y de video solo acepta archivos que hayas subido tú. Para reutilizar una imagen generada, pasa su
urlde salida. - Una solicitud que hace referencia a un archivo no se traslada a otro canal si falla. No la reintentes en un canal distinto sin revisar el error.
- Conserva el archivo hasta que todas las tareas que lo referencian alcancen un estado terminal. Eliminarlo antes puede hacer que la tarea falle.
Comprobar la compatibilidad del modelo
Un archivo almacenado no se puede usar automáticamente con todos los modelos. El modelo debe declarar la modalidad de entrada correspondiente en el catálogo público:
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
| jq '.data.input_modalities'["text", "image", "file"]| Para enviar | input_modalities debe incluir |
|---|---|
| Un PDF | file |
| Una imagen | image |
| Un MP4 | video |
| Un archivo de audio | audio |
Una lista vacía o ausente significa que los ID de archivo no están habilitados para ese modelo. En ese caso, la solicitud falla con file_model_unsupported. No deduzcas la compatibilidad a partir del nombre del modelo.
Límites
| Límite | Valor |
|---|---|
| Tamaño de carga | 100 MiB (104,857,600 bytes) por archivo; los archivos vacíos se rechazan |
| Bytes referenciados por solicitud a un modelo | 50,000,000 bytes en total |
| Referencias por solicitud a un modelo | 100 |
| Longitud del nombre de archivo | 255 caracteres |
Hacer referencia al mismo archivo dos veces cuenta dos veces para ambos límites por solicitud. Un archivo de entre 50 MB y 100 MiB se puede subir, pero no se puede referenciar en una solicitud a un modelo. Un modelo o un canal puede aplicar un límite inferior.
Tipos de archivo
El tipo se detecta a partir del contenido del archivo, no de su extensión ni del Content-Type de la parte.
| Tipo | Formatos | Se puede referenciar en |
|---|---|---|
| Messages, Responses | ||
| Imagen | PNG, JPEG, GIF, WebP | Messages, Responses, generación de imágenes, generación de video |
| Video | MP4 | Generación de video |
| Audio | MP3, WAV, FLAC, OGG | Generación de video |
| Office | DOCX, XLSX, PPTX | Solo almacenamiento |
| Texto | Texto UTF-8, almacenado como text/plain | Solo almacenamiento |
Cualquier otro contenido se rechaza con invalid_file.
Nombres de archivo
Un nombre de archivo no puede contener <, >, :, ", |, ?, *, \ ni caracteres de control. / se permite como separador, pero no los segmentos vacíos, . ni ...
Administrar archivos
Los archivos pertenecen a tu cuenta. Todas las claves de API de la cuenta ven los mismos archivos; otras cuentas no pueden usar tus ID de archivo.
Listar archivos
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
-H "Authorization: Bearer ${FELO_API_KEY}"{
"data": [
{
"id": "felo_file_0179...",
"type": "file",
"source": "upload",
"filename": "report.pdf",
"mime_type": "application/pdf",
"size_bytes": 482113,
"created_at": "2026-11-10T02:25:41Z",
"downloadable": false
}
],
"first_id": "felo_file_0179...",
"last_id": "felo_file_0179...",
"cursor": "felo_file_0179...",
"has_more": false
}Los resultados se ordenan del más antiguo al más reciente. Cuando has_more es true, pasa el cursor devuelto para obtener la página siguiente. No hay búsqueda ni filtro por tipo en el servidor.
Obtener un archivo
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"Eliminar un archivo
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
-H "Authorization: Bearer ${FELO_API_KEY}"{"id": "felo_file_0179...", "type": "file_deleted"}La eliminación surte efecto de inmediato y no se puede deshacer. Un 503 significa que la eliminación no se completó; vuelve a enviar el DELETE.
Descargas
Los archivos subidos no se pueden descargar. GET /api/v1/files/{file_id}/content devuelve 400 file_not_downloadable, y el encabezado Location de la respuesta de carga apunta a los metadatos del archivo, no a sus bytes. Conserva tu propia copia de todo lo que subas.
Para descargar medios generados, usa las URL firmadas de outputs de la tarea.
Referencia de la API
Todos los endpoints usan Authorization: Bearer YOUR_API_KEY. Las respuestas correctas son objetos JSON simples, sin sobre.
| Método | Ruta | Devuelve |
|---|---|---|
POST | /api/v1/files | El objeto de archivo |
GET | /api/v1/files | Una página de archivos |
GET | /api/v1/files/{file_id} | El objeto de archivo |
DELETE | /api/v1/files/{file_id} | {"id": "...", "type": "file_deleted"} |
GET | /api/v1/files/{file_id}/content | 400 file_not_downloadable |
POST, DELETE y el GET de un solo archivo rechazan cualquier parámetro de consulta con invalid_query.
Objeto de archivo
| Campo | Tipo | Descripción |
|---|---|---|
id | string | ID de archivo, con el prefijo felo_file_. Úsalo como file_id |
type | string | Siempre file |
source | string | upload para los archivos que subiste, generated para las salidas de modelos |
filename | string | El nombre enviado con la carga |
mime_type | string | Tipo detectado a partir del contenido |
size_bytes | integer | Tamaño en bytes |
created_at | string | Marca de tiempo UTC en formato ISO 8601 |
downloadable | boolean | false para los archivos subidos |
Solicitud de carga
| Parte | Obligatorio | Descripción |
|---|---|---|
file | Sí | El archivo, enviado como una parte de archivo de multipart/form-data con un nombre de archivo |
La respuesta incluye un encabezado Location con la URL de los metadatos del archivo.
Parámetros de listado
| Parámetro | Valor predeterminado | Descripción |
|---|---|---|
limit | 100 | Tamaño de página, de 1 a 1000 |
cursor | El valor de cursor de la página anterior | |
after, after_id | Alias de cursor. Envía solo uno de los tres | |
order | asc | Solo se admite asc |
| Campo de la respuesta | Tipo | Descripción |
|---|---|---|
data | array | Objetos de archivo, del más antiguo al más reciente |
first_id | string o null | ID del primer archivo de la página |
last_id | string o null | ID del último archivo de la página |
cursor | string o null | Valor que se pasa como cursor para la página siguiente |
has_more | boolean | Indica si existe otra página |
Errores
Los endpoints de Files, Responses y la generación de imágenes y de video usan el sobre de error de OpenAI:
{
"error": {
"message": "This model does not accept this attachment type",
"type": "invalid_request_error",
"param": "frame_images.0.image_url",
"code": "file_model_unsupported"
}
}param es null en los errores de los endpoints de Files. Messages devuelve el formato de error de Anthropic, que no tiene error.code. El ID de solicitud está en el encabezado de respuesta X-Request-Id.
Errores al subir o administrar archivos:
| HTTP | error.code | Significado |
|---|---|---|
| 400 | invalid_content_type | El cuerpo no es multipart/form-data |
| 400 | invalid_file | Falta la parte file, hay una parte adicional, el archivo está vacío o el contenido no es compatible |
| 400 | invalid_filename | El nombre de archivo es demasiado largo o contiene un carácter no permitido |
| 413 | file_too_large | El archivo supera los 100 MiB |
| 400 | invalid_query | Un parámetro de consulta no admitido, o un order distinto de asc |
| 400 | invalid_limit | limit está fuera del rango de 1 a 1000 |
| 400 | invalid_cursor | El cursor tiene un formato incorrecto, o se envió más de un cursor |
| 400 | file_not_downloadable | Se solicitó /content |
| 404 | file_not_found | El archivo no existe, se eliminó o pertenece a otra cuenta |
| 503 | file_storage_unavailable | El almacenamiento de archivos no está disponible temporalmente; vuelve a intentarlo más tarde |
| 503 | file_upload_expired | La carga no se completó a tiempo; vuelve a subir el archivo |
Errores al hacer referencia a un archivo en una solicitud a un modelo:
| HTTP | error.code | Significado |
|---|---|---|
| 400 | invalid_file_input | ID con formato incorrecto, file_id y url a la vez en un mismo localizador, o más de 100 referencias |
| 400 | unsupported_file_type | El tipo del archivo no corresponde a la posición, por ejemplo un MP4 en un bloque de documento |
| 400 | file_model_unsupported | El modelo no declara la modalidad de entrada requerida |
| 400 | file_input_too_large | Los archivos referenciados superan los 50,000,000 bytes en total |
| 400 | file_protocol_unsupported | Se envió un ID de archivo a Chat Completions |
| 404 | file_not_found | El archivo no existe, se eliminó, pertenece a otra cuenta o es un archivo generado enviado a la generación de imágenes o de video |
En la generación de imágenes y de video, un archivo también puede fallar después del 202. En ese caso, la tarea termina como failed con uno de estos códigos en error.code.
Los errores de autenticación, saldo y límite de frecuencia se describen en Errores, límites y reintentos.
Relacionado
¿Necesitas ayuda?
- Para dudas sobre la API, la facturación o tu cuenta, contacta con soporte.
- Habla con los desarrolladores de Felo en Discord.
- Consulta nuestro registro de cambios.
- ¿Necesitas precios por volumen o ayuda con la compra? Habla con ventas.
- ¿Estás creando con un LLM? Lee llms.txt.