La API de Archivos de Claude te permite subir un archivo una sola vez a https://api.anthropic.com/v1/files, obtener un file_id y hacer referencia a ese ID en cualquier solicitud de Messages en lugar de volver a enviar el contenido cada vez. Desde el 20 de agosto de 2026, está disponible de forma general en la Plataforma Claude: sin encabezado beta, 1 TB de almacenamiento por organización y límites de velocidad cinco veces mayores que en la beta. Anthropic anunció el cambio en su publicación sobre agentes de producción, junto con la disponibilidad general de computer use, la herramienta de navegador y la API de Skills.
Esta guía cubre el ciclo de vida completo: subir archivos, referenciarlos en mensajes, descargar resultados generados, la expiración, el modelo de seguridad del espacio de trabajo y los límites con los que te toparás en producción. Como cada paso aquí es una llamada HTTP, tu agente de programación puede convertir todo el flujo en un escenario de prueba de Apidog CLI en lugar de un montón de comandos curl sueltos.
Qué hace la API de Archivos
La API de Archivos es una capa de almacenamiento de crear-una-vez, usar-muchas-veces para la API de Claude. Resuelve un costo específico: si tu aplicación hace preguntas sobre el mismo PDF de 40 páginas a lo largo de cientos de solicitudes, volver a subir ese PDF en cada solicitud desperdicia ancho de banda y complica el código de tu cliente. Con la API de Archivos tú:
- Subes un archivo al almacenamiento de Anthropic y recibes un
file_idúnico - Referencias ese ID en las solicitudes de Messages mediante un bloque de contenido
- Descargas archivos que generan las skills o la herramienta de ejecución de código (gráficos, hojas de cálculo, presentaciones)
- Gestionas todo con operaciones de listar, recuperar metadatos y eliminar
La superficie de endpoints es pequeña:
| Operación | Endpoint |
|---|---|
| Subir un archivo | POST /v1/files |
| Listar archivos | GET /v1/files |
| Obtener metadatos de un archivo | GET /v1/files/{file_id} |
| Descargar el contenido de un archivo | GET /v1/files/{file_id}/content |
| Eliminar un archivo | DELETE /v1/files/{file_id} |
Todo funciona con los encabezados estándar x-api-key y anthropic-version: 2023-06-01. Si eres nuevo en la propia API de Messages, nuestra guía de la API de Claude Opus 5 cubre lo básico de autenticación y estructura de solicitudes.
Qué cambió con la disponibilidad general
La API de Archivos pasó meses en beta detrás de un encabezado. La versión GA del 20 de agosto de 2026 cambió cuatro cosas que importan para la planificación de producción:
- Sin encabezado beta. Las solicitudes funcionan con encabezados estándar en la API de Claude.
- Límites de velocidad 5 veces mayores. Las operaciones con archivos ahora permiten aproximadamente 500 solicitudes por minuto, con límites más altos disponibles a través de ventas.
- 1 TB de almacenamiento por organización, con un tope de 500 MB por archivo.
- Cobertura de plataforma más amplia. La API de Archivos se ejecuta directamente en la API de Claude, en Claude Platform on AWS en beta y en Microsoft Foundry cuando se usa un despliegue Hosted on Anthropic. No está disponible en Amazon Bedrock ni en Google Cloud Vertex AI, y no es elegible para acuerdos de retención cero de datos. Planifica en consecuencia si tienes una política de retención estricta.
Subir un archivo
Las subidas son solicitudes de formulario multipart, no JSON:
curl -X POST https://api.anthropic.com/v1/files \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-F "file=@/path/to/report.pdf"
La respuesta te da todo lo que necesitas para referenciar el archivo más adelante:
{
"id": "file_011CNha8iCJcU1wXNR6q4V8w",
"type": "file",
"filename": "report.pdf",
"mime_type": "application/pdf",
"size_bytes": 1024000,
"created_at": "2026-08-24T00:00:00Z",
"downloadable": false,
"expires_at": null
}
Dos campos merecen atención. downloadable es false para cualquier cosa que subas; solo los archivos que Claude genera mediante skills o ejecución de código se pueden descargar. Y expires_at es null a menos que establezcas una expiración al momento de subir (más sobre esto abajo).
En la prueba de Apidog CLI que aparece más abajo, el paso de subida guarda id como una variable, de modo que cada solicitud posterior referencia {{claude_file_id}} en lugar de una cadena codificada de forma fija.
Referenciar archivos en mensajes
Una vez subido, el archivo se integra en una solicitud de Messages a través de uno de tres tipos de bloques de contenido, según el archivo:
| Tipo de archivo | Tipo MIME | Bloque de contenido |
|---|---|---|
| PDF, texto plano | application/pdf, text/plain |
document |
| Imágenes | image/jpeg, image/png, image/gif, image/webp |
image |
| Conjuntos de datos y todo lo demás | varía | container_upload (herramienta de ejecución de código) |
Una solicitud de resumen de PDF se ve así:
curl -X POST https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-5",
"max_tokens": 1024,
"messages": [{
"role": "user",
"content": [
{"type": "text", "text": "Summarize this document."},
{"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}}
]
}]
}'
El bloque document también acepta los campos opcionales title, context y citations, para que puedas habilitar la salida de citas sobre el archivo subido. Para imágenes, cambia el tipo de bloque a image con la misma estructura de source. Para hojas de cálculo, CSV que quieras analizar en lugar de leer, o cualquier formato que el bloque document no acepte, usa container_upload para entregar el archivo a la herramienta de ejecución de código.
Una nota sobre formatos: .docx y .xlsx no son compatibles directamente con el bloque document. Convierte los archivos de Word a PDF para conservar el análisis de imágenes y las citas, o extrae el texto plano y envíalo en línea.
Descargar archivos generados
El endpoint de descarga existe para la salida, no para la entrada. Cuando Claude crea un gráfico con ejecución de código o produce una hoja de cálculo mediante una skill, la respuesta incluye un file_id dentro del bloque bash_code_execution_tool_result. Ese ID sí es descargable:
curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
--output chart.png
Intentar descargar un archivo que tú subiste devuelve un 400. Revisa la bandera downloadable en los metadatos antes de armar lógica de reintentos alrededor de esto; te ahorra un ticket de soporte. Este bucle de subir-entrada, generar-salida es la columna vertebral del flujo de trabajo de la API de Skills recién declarada GA, donde las skills producen documentos de Office que descargas a través de este mismo endpoint. Nuestra guía sobre Claude Skills cubre qué son las skills y cómo se ejecutan.
Expiración y ciclo de vida de los archivos
Los archivos persisten hasta que los elimines o hasta que se cumpla una expiración que establezcas al subirlos:
- Pasa
expires_in_secondscomo campo de formulario al subir. Rango válido: 3.600 (1 hora) a 7.776.000 (90 días). Se establece una sola vez y no se puede cambiar después. - Una vez que pasa
expires_at, las descargas de contenido devuelven 404 y cualquier solicitud de Messages que haga referencia al archivo falla antes de la inferencia. - Los metadatos siguen siendo legibles hasta 30 días después de la expiración, y los archivos expirados aún aparecen en las respuestas de listado durante esa ventana. Compara
expires_atcon la hora actual al filtrar. - Eliminar un archivo lo quita de inmediato y no se puede deshacer. El contenido expirado se libera de tu cuota de almacenamiento, pero puede conservarse brevemente para revisión de seguridad, así que la expiración es una herramienta de ciclo de vida, no un control de eliminación garantizada.
El modelo de seguridad: los archivos están delimitados por el espacio de trabajo
Este es el borde más afilado de toda la API. Los archivos subidos son accesibles para todo tu espacio de trabajo, no están delimitados a un usuario final, conversación o sesión. Cualquier clave de API en el mismo espacio de trabajo puede leer cualquier archivo subido allí, y todas las claves comparten el espacio de trabajo predeterminado de tu organización a menos que las asignes a otro.
Las reglas prácticas:
- Nunca aceptes valores de
file_idprovenientes de usuarios finales. Un ID proporcionado por el usuario permitiría que un usuario de tu aplicación lea las subidas de otro. Trata los IDs de archivo como referencias del lado del servidor y mantén la correspondencia usuario-a-archivo en tu propia base de datos. - ¿Construyes multiinquilino? Un espacio de trabajo por inquilino. El espacio de trabajo es la frontera de aislamiento. Cada organización obtiene hasta 100 espacios de trabajo, y los equipos de cuenta de Anthropic pueden aumentar esa cifra.
Si ya estás haciendo seguimiento de claves de API por inquilino para la atribución de costos (un tema que exploramos a fondo en cómo reducir tu factura de la API de Claude), la misma disposición de espacios de trabajo te da aislamiento de archivos gratis.
Límites y facturación
Los números con los que debes planificar:
| Límite | Valor |
|---|---|
| Tamaño máximo de archivo | 500 MB |
| Almacenamiento de la organización | 1 TB |
| Límite de velocidad de la API de Archivos | ~500 solicitudes/minuto |
| Longitud del nombre de archivo | 1 a 255 caracteres |
| Rango de expiración | 1 hora a 90 días |
La facturación es amigable: subir, descargar, listar y eliminar archivos son gratuitos. Solo pagas cuando el contenido de un archivo entra en una solicitud de Messages, donde se factura como tokens de entrada normales. Un PDF de 100 páginas referenciado en diez solicitudes cuesta los mismos tokens de entrada diez veces; la API de Archivos te ahorra ancho de banda y complejidad en el cliente, no gasto en tokens. Para ahorrar del lado de los tokens, combina las referencias de archivos con el almacenamiento en caché de prompts.
Ojo con estos errores: 413 cuando un archivo supera los 500 MB, 400 cuando tu organización alcanza el techo de 1 TB, 400 cuando el tipo de un archivo no coincide con su bloque de contenido (una imagen en un bloque document, por ejemplo) y 404 para IDs fuera de tu espacio de trabajo.
Deja que Claude Code pruebe la API de Archivos con Apidog CLI
La API de Archivos es un flujo con estado y de varios pasos, así que merece una prueba de regresión, no el historial del shell. Claude Code, o cualquier agente de programación, puede construir y ejecutar esa prueba a través de Apidog CLI. Configúralo una vez:
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
El token proviene de Apidog, en Account Settings, API Access Token. Luego dale al agente un solo prompt:
Use Apidog CLI on project <id>. Add the Files API endpoints (upload, list,
metadata, download, delete) and POST /v1/messages, with x-api-key from
{{ANTHROPIC_API_KEY}} and the anthropic-version header. Build a test scenario:
upload with expires_in_seconds=3600 and assert expires_at is set, save the id
as claude_file_id, reference it in a Messages call and assert 200, delete it,
then assert the metadata call returns 404. Run it and summarize any failures.
Los comandos que ejecuta, verificados con Apidog CLI 2.2.7:
apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file files-upload.json
apidog test-scenario create --project <id> --name "Files API lifecycle" --priority 1
apidog test-scenario import-steps <scenarioId> --project <id> --source endpoint \
--ids <uploadId>,<messagesId>,<deleteId>,<metadataId> --sync manual
apidog cli-schema validate test-scenario-update --file lifecycle.json
apidog test-scenario update <scenarioId> --project <id> --file lifecycle.json
apidog run -t <scenarioId> --project <id> -e <envId> \
--env-var "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" -r cli,json
El agente repite endpoint create para cada endpoint, y luego escribe la extracción de variables y las aserciones en el escenario antes de ejecutarlo. Cambiar de archivo de prueba después significa modificar un solo paso de subida, no cada solicitud. Pide también un mock de la respuesta de subida (apidog mock create), y el equipo de frontend obtiene la forma del JSON antes de que exista tu proxy de backend. La misma línea de apidog run con -r junit se integra en CI; nuestra guía de Apidog CLI en Claude Code cubre la configuración del agente de principio a fin.
Preguntas frecuentes
¿Todavía necesito un encabezado beta? No. Desde la GA del 20 de agosto de 2026, la API de Archivos funciona en la API de Claude con los encabezados estándar x-api-key y anthropic-version. Si tu SDK o proxy todavía fija el antiguo encabezado beta de files, elimínalo cuando actualices.
¿Puedo actualizar el contenido de un archivo? No. Los archivos son inmutables después de subirlos. Sube un archivo nuevo, apunta tus referencias al nuevo ID y elimina el antiguo.
¿La API de Archivos funciona en Bedrock o Vertex AI? No. Está en la API de Claude, Claude Platform on AWS (beta) y Microsoft Foundry con un despliegue Hosted on Anthropic. En Bedrock y Vertex todavía necesitas contenido base64 en línea.
¿La API de Archivos es lo mismo que la API de Skills usa para las salidas? Sí. Las skills y la herramienta de ejecución de código escriben los documentos que generan en el mismo almacén de archivos, y los descargas a través de GET /v1/files/{file_id}/content. El lado de la API de Skills de ese flujo de trabajo combina bien con las pruebas automatizadas.
Para cerrar
Que la API de Archivos haya pasado a GA elimina la última excusa para meter el mismo documento en base64 en cada solicitud. Sube una vez, referencia por ID, establece una expiración y mantén los archivos de cada inquilino en espacios de trabajo separados. La superficie de la API son cinco endpoints, y todos ellos se pueden probar en minutos: haz que tu agente de programación escriba el flujo con Apidog CLI, encadena el file_id a través de una variable y añade todo el ciclo de vida a CI antes de que tus usuarios encuentren los casos límite por ti.