Felo API PlatformFelo API Platform

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

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-data con exactamente una parte, llamada file. Cualquier otra parte, incluida purpose, se rechaza con invalid_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ía purpose, 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

EndpointTipos de archivoModalidad de entrada requeridaCampo
POST /api/v1/messagesPDF, imagenfile, imagemessages[].content[]
POST /api/v1/responsesPDF, imagenfile, imageinput[].content[]
POST /api/v1/images/generationsImagenimageinput_references[]
POST /api/v1/videos/generationsImagenimageframe_images[]
POST /api/v1/videos/generationsImagen, MP4, audioimage, video, audioinput_references[]
POST /api/v1/chat/completionsNo 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

ArchivoBloque de contenido
PDF{"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_url o audio_url contiene exactamente uno de los campos file_id o url, y ningún otro.
  • Un mismo array puede mezclar entradas que usan file_id con entradas que usan url.
  • La generación de imágenes y de video solo acepta archivos que hayas subido tú. Para reutilizar una imagen generada, pasa su url de 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 enviarinput_modalities debe incluir
Un PDFfile
Una imagenimage
Un MP4video
Un archivo de audioaudio

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ímiteValor
Tamaño de carga100 MiB (104,857,600 bytes) por archivo; los archivos vacíos se rechazan
Bytes referenciados por solicitud a un modelo50,000,000 bytes en total
Referencias por solicitud a un modelo100
Longitud del nombre de archivo255 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.

TipoFormatosSe puede referenciar en
PDFPDFMessages, Responses
ImagenPNG, JPEG, GIF, WebPMessages, Responses, generación de imágenes, generación de video
VideoMP4Generación de video
AudioMP3, WAV, FLAC, OGGGeneración de video
OfficeDOCX, XLSX, PPTXSolo almacenamiento
TextoTexto UTF-8, almacenado como text/plainSolo 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étodoRutaDevuelve
POST/api/v1/filesEl objeto de archivo
GET/api/v1/filesUna 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}/content400 file_not_downloadable

POST, DELETE y el GET de un solo archivo rechazan cualquier parámetro de consulta con invalid_query.

Objeto de archivo

CampoTipoDescripción
idstringID de archivo, con el prefijo felo_file_. Úsalo como file_id
typestringSiempre file
sourcestringupload para los archivos que subiste, generated para las salidas de modelos
filenamestringEl nombre enviado con la carga
mime_typestringTipo detectado a partir del contenido
size_bytesintegerTamaño en bytes
created_atstringMarca de tiempo UTC en formato ISO 8601
downloadablebooleanfalse para los archivos subidos

Solicitud de carga

ParteObligatorioDescripción
fileSí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ámetroValor predeterminadoDescripción
limit100Tamaño de página, de 1 a 1000
cursorEl valor de cursor de la página anterior
after, after_idAlias de cursor. Envía solo uno de los tres
orderascSolo se admite asc
Campo de la respuestaTipoDescripción
dataarrayObjetos de archivo, del más antiguo al más reciente
first_idstring o nullID del primer archivo de la página
last_idstring o nullID del último archivo de la página
cursorstring o nullValor que se pasa como cursor para la página siguiente
has_morebooleanIndica 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:

HTTPerror.codeSignificado
400invalid_content_typeEl cuerpo no es multipart/form-data
400invalid_fileFalta la parte file, hay una parte adicional, el archivo está vacío o el contenido no es compatible
400invalid_filenameEl nombre de archivo es demasiado largo o contiene un carácter no permitido
413file_too_largeEl archivo supera los 100 MiB
400invalid_queryUn parámetro de consulta no admitido, o un order distinto de asc
400invalid_limitlimit está fuera del rango de 1 a 1000
400invalid_cursorEl cursor tiene un formato incorrecto, o se envió más de un cursor
400file_not_downloadableSe solicitó /content
404file_not_foundEl archivo no existe, se eliminó o pertenece a otra cuenta
503file_storage_unavailableEl almacenamiento de archivos no está disponible temporalmente; vuelve a intentarlo más tarde
503file_upload_expiredLa carga no se completó a tiempo; vuelve a subir el archivo

Errores al hacer referencia a un archivo en una solicitud a un modelo:

HTTPerror.codeSignificado
400invalid_file_inputID con formato incorrecto, file_id y url a la vez en un mismo localizador, o más de 100 referencias
400unsupported_file_typeEl tipo del archivo no corresponde a la posición, por ejemplo un MP4 en un bloque de documento
400file_model_unsupportedEl modelo no declara la modalidad de entrada requerida
400file_input_too_largeLos archivos referenciados superan los 50,000,000 bytes en total
400file_protocol_unsupportedSe envió un ID de archivo a Chat Completions
404file_not_foundEl 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?