# 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](https://openapi.felo.ai/es/docs/authentication.md).
- 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](#comprobar-la-compatibilidad-del-modelo).

## Inicio rápido

### 1. Subir el archivo

```bash
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:

```json
{
  "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

```bash
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:

```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:

```javascript
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

| 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

```json
{
  "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 |
|---|---|
| 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

```json
{
  "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](https://openapi.felo.ai/es/docs/guides/image-generation.md).

### Generación de video

Los fotogramas inicial y final van en `frame_images`:

```json
{
  "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:

```json
{
  "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:

```bash
curl -s "https://openapi.felo.ai/api/platform/model-catalog/model?model=claude-haiku-4-5" \
  | jq '.data.input_modalities'
```

```json
["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 |
|---|---|---|
| PDF | PDF | 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

```bash
curl "https://openapi.felo.ai/api/v1/files?limit=100" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{
  "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

```bash
curl "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

### Eliminar un archivo

```bash
curl -X DELETE "https://openapi.felo.ai/api/v1/files/${FILE_ID}" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
```

```json
{"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](#objeto-de-archivo) |
| `GET` | `/api/v1/files` | Una [página de archivos](#par-metros-de-listado) |
| `GET` | `/api/v1/files/{file_id}` | El [objeto de archivo](#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:

```json
{
  "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](https://openapi.felo.ai/es/docs/guides/errors-and-limits.md).

## Relacionado

- [Protocolos y SDKs](https://openapi.felo.ai/es/docs/guides/protocols.md)
- [Generación de imágenes](https://openapi.felo.ai/es/docs/guides/image-generation.md)
- [Tareas asíncronas](https://openapi.felo.ai/es/docs/guides/async-tasks.md)
- [Referencia de API de modelos](https://openapi.felo.ai/es/docs/model-api)
