Files API

La Files API te permite subir y administrar archivos para usarlos con la Claude API sin volver a subir el contenido con cada solicitud. Esto es particularmente útil cuando usas la herramienta de ejecución de código para proporcionar entradas (por ejemplo, conjuntos de datos y documentos) y luego descargar salidas (por ejemplo, gráficos). Puedes explorar la referencia de la API directamenteVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver., además de esta guía.

Compatibilidad de tipos de archivo

Hacer referencia a un file_id en una solicitud de Messages es compatible con todos los modelos que admiten el tipo de archivo dado. Las imágenes son compatibles con todos los modelos actuales de Claude. Para PDFs y otros tipos de archivo con la herramienta de ejecución de código, consulta las páginas enlazadas para conocer la compatibilidad de modelos.

Cómo funciona la Files API

La Files API proporciona un enfoque de crear una vez y usar muchas veces para trabajar con archivos:

• Sube archivos al almacenamiento seguro de Anthropic y recibe un file_id único
• Descarga archivos creados por skills o la herramienta de ejecución de código
• Haz referencia a archivos en solicitudes de MessagesVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. usando el file_id en lugar de volver a subir el contenido
• Administra tus archivos con operaciones de listar, recuperar y eliminar

Cómo usar la Files API

Subir un archivo

Sube un archivo para hacer referencia a él en futuras llamadas a la API:

uploaded = client.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)

La respuesta al subir un archivo incluye:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

downloadableVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. es false para los archivos que subes. Solo se pueden descargar los archivos creados por skills o por la herramienta de ejecución de código. Consulta Descargar un archivo.

La referencia de la API describe cada campo del objeto de archivo.

Usar un archivo en mensajes

Una vez subido, haz referencia al archivo pasando el id de la respuesta de subida como file_id:

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please summarize this document for me."},
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": file_id,
                    },
                },
            ],
        }
    ],
)
print(response)

Tipos de archivo y bloques de contenido

La Files API admite diferentes tipos de archivo que corresponden a diferentes tipos de bloques de contenido:

Bloques de documento

Para PDFs y archivos de texto, usa el bloque de contenido document:

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // Optional
  "context": "Context about the document", // Optional
  "citations": { "enabled": true } // Optional, enables citations
}

Bloques de imagen

Para imágenes, usa el bloque de contenido image:

{
  "type": "image",
  "source": {
    "type": "file",
    "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
  }
}

Bloques de carga a contenedor

Para enviar un archivo a la herramienta de ejecución de código, usa el bloque de contenido container_upload:

{
  "type": "container_upload",
  "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}

Trabajar con otros formatos de archivo

Para tipos de archivo que el bloque document no admite (por ejemplo, .docx y .xlsx), convierte los archivos a texto sin formato e incluye el contenido directamente en tu mensaje. Los archivos que ya son texto sin formato, como los archivos .csv y .md, pueden leerse de esta manera o subirse a través de la Files API con un tipo de contenido text/plain explícito. Para analizar conjuntos de datos en lugar de leerlos como texto, súbelos para la herramienta de ejecución de código usando un bloque container_upload (consulta Sube y analiza tus propios archivos).

Los siguientes ejemplos leen un archivo de texto y envían su contenido como texto plano:

client = anthropic.Anthropic()

# Lee el archivo de texto
with open("document.txt") as f:
    text_content = f.read()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the document content:\n\n{text_content}\n\nPlease summarize this document.",
                }
            ],
        }
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Administrar archivos

Listar archivos

Obtén una lista de tus archivos subidos. El endpoint está paginado: cada solicitud devuelve hasta limitVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. archivos (20 de forma predeterminada y como máximo 1,000), y el cursor next_pageVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. de la respuesta obtiene la página siguiente cuando lo pasas de vuelta como el parámetro pageVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver.. Los archivos se ordenan del más reciente al más antiguo. Consulta la referencia de la API Listar archivosVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver.. El SDK devuelve la primera página y proporciona utilidades de paginación automática.

client = anthropic.Anthropic()
files = client.files.list()
print(files)

Para verificar un conjunto conocido de archivos en una sola solicitud en lugar de paginar, pasa hasta 100 IDs de archivo como parámetros de consulta ids[]. Una solicitud con ids[] siempre devuelve una sola página (next_page es null), y cualquier ID que no corresponda a un archivo en tu workspace se omite silenciosamente de data; compara los IDs devueltos con los IDs solicitados para detectar los faltantes. ids[] no puede combinarse con page ni con limit.

Obtener metadatos de un archivo

Recupera información sobre un archivo específico:

file = client.files.retrieve_metadata(file_id)
print(file)

Eliminar un archivo

Elimina un archivo de tu espacio de trabajo:

client.files.delete(file_id)

Descargar un archivo

Descarga archivos que fueron creados por skills o la herramienta de ejecución de código. Los archivos que subes no pueden descargarse. El file_id de un archivo generado aparece en el bloque de contenido bash_code_execution_tool_result de la respuesta de Messages que lo creó:

file_content = client.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")

En la Claude API, los archivos de imagen, video y audio compatibles que Claude produce con la herramienta de ejecución de código, incluidos los archivos creados por skills, llevan Content Credentials C2PA firmadas cuando los descargas. Consulta Content Credentials en archivos generados para saber qué contiene la credencial y cómo verificarla.

Almacenamiento de archivos y límites

Límites de almacenamiento

• Tamaño máximo de archivo: 500 MB por archivo
• Almacenamiento total: 1 TB por organización

Ciclo de vida de los archivos

• Los archivos están limitados al espacio de trabajo en el que se subieron. Cualquier solicitud en el mismo espacio de trabajo puede hacer referencia a ellos; nunca aceptes ID de archivo de fuentes no confiables (consulta la advertencia sobre el acceso al espacio de trabajo).
• Los archivos no se pueden modificar ni renombrar después de subirlos. Para cambiar el contenido de un archivo, sube un archivo nuevo y elimina el anterior.
• Los archivos persisten hasta que los eliminas con el endpoint DELETE /v1/files/{file_id} o hasta que alcanzan su expires_at.
• Los archivos eliminados no se pueden recuperar.
• Los archivos dejan de ser accesibles a través de la API poco después de su eliminación, pero pueden persistir en llamadas activas a la Messages API y en los usos de herramientas asociados.
• Los archivos que eliminan los usuarios se eliminarán de acuerdo con la política de retención de datos de Anthropic.

Expiración de archivos

Para que un archivo caduque automáticamente, incluye un campo de formulario expires_in_secondsVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. al subirlo. El valor es un número entero de segundos entre 3,600 (1 hora) y 7,776,000 (90 días). La marca de tiempo expires_atVista previa disponible con enlaces a la referencia de la API — presiona Tab hasta que el foco entre a la tarjeta y Escape para volver. resultante (RFC 3339) aparece en cada respuesta de archivo y es null para los archivos subidos sin caducidad. La caducidad se establece una sola vez al subir el archivo y no se puede cambiar.

Cuando un archivo alcanza su expires_at:

• Descargar su contenido (GET /v1/files/{file_id}/content) devuelve un error 404.
• Una solicitud de Messages que hace referencia al archivo falla antes de la inferencia.
• Sus metadatos (GET /v1/files/{file_id}) siguen siendo legibles hasta por 30 días, con expires_at en el pasado.
• Sigue apareciendo en las respuestas de listado durante ese período; compara expires_at con la hora actual para filtrar los archivos expirados.

Eliminar un archivo expirado con DELETE /v1/files/{file_id} elimina sus metadatos de inmediato en lugar de esperar a que transcurra el período de 30 días.

Registro de auditoría

Si tu organización tiene habilitada la Compliance API, su Activity Feed registra las operaciones de la Files API realizadas con una clave de API de Claude o desde la Claude Console: cada subida (POST /v1/files), descarga de contenido (GET /v1/files/{file_id}/content) y eliminación (DELETE /v1/files/{file_id}) aparece como una actividad platform_file_uploaded, platform_file_content_downloaded o platform_file_deleted. Listar archivos y recuperar metadatos de archivos no se registra. Las operaciones que ocurren mientras la Compliance API está desactivada no se registran y no pueden recuperarse después, así que configura la Compliance API antes de depender de este registro de auditoría. En Claude Platform on AWS, audita las operaciones de archivos con eventos de datos de AWS CloudTrail en su lugar.

Migrar desde files-api-2025-04-14

La Files API salió de beta y no necesita ningún encabezado beta. Migrar desde files-api-2025-04-14 es opcional: las solicitudes que lo envían siguen funcionando y siguen devolviendo las formas de respuesta beta, por lo que una integración existente sigue funcionando hasta que la cambies. Quitar el encabezado cambia esas solicitudes a las formas documentadas en esta página:

Para migrar:

1. Quita el encabezado beta. Elimina anthropic-beta: files-api-2025-04-14 de tus solicitudes. Con el SDK, llama a client.files en lugar de client.beta.files; mantener client.beta.files solo funciona en las versiones del SDK que ya no envían el encabezado. Las versiones anteriores lo envían desde client.beta.files incluso cuando no pasas nombres beta.
2. Actualiza la paginación. Reemplaza los bucles de after_id/before_id por el cursor page/next_page, o usa las utilidades de paginación automática del SDK que se muestran en Administrar archivos.
3. Lee expires_at. El campo aparece solo sin el encabezado; null significa que el archivo no tiene expiración (consulta Expiración de archivos).

Espacio de nombres beta del SDK

A partir de Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, PHP SDK 0.45.0, Ruby SDK 1.67.0 y C# SDK 12.44.0, client.beta.files ya no envía files-api-2025-04-14 y devuelve las mismas estructuras que client.files, con nombres de tipo con el prefijo Beta (en PHP, clases en el espacio de nombres Anthropic\Beta). Acepta nombres beta mediante betas para funciones de Files que están en beta, como el filtrado por scope_id bajo un encabezado beta de Managed Agents. Las versiones anteriores del SDK están tipadas con las estructuras beta; si dependes de esos tipos, permanece en una versión anterior hasta que migres.

Las solicitudes que llevan anthropic-beta: managed-agents-2026-04-01 sin files-api-2025-04-14 reciben las formas de esta página con una concesión de compatibilidad en GET /v1/files: before_id y after_id todavía se aceptan (no combinables con page ni con ids[]), y la respuesta de listado incluye has_more, first_id y last_id junto con next_page. Las versiones beta posteriores de Managed Agents reciben la forma simple.

Manejo de errores

Los errores comunes al usar la Files API incluyen:

• Archivo no encontrado (404): El file_id especificado no existe o no tienes acceso a él.
• Tipo de archivo no válido (400): El tipo de archivo no coincide con el tipo de bloque de contenido (por ejemplo, usar un archivo de imagen en un bloque de documento).
• No descargable (400): Los archivos que subes tienen "downloadable": false y no se pueden descargar. Solo se pueden descargar los archivos creados por skills o la herramienta de ejecución de código.
• Excede el tamaño de la ventana de contexto (400): El archivo es más grande que el tamaño de la “context window” (ventana de contexto) (por ejemplo, usar un archivo de texto sin formato de 500 MB en una solicitud a /v1/messages).
• Nombre de archivo no válido (400): El nombre del archivo no cumple los requisitos de longitud (1–255 caracteres) o contiene caracteres prohibidos (<, >, :, ", |, ?, *, \, / o caracteres Unicode 0–31).
• Archivo demasiado grande (413): El archivo excede el límite de 500 MB.
• Límite de almacenamiento excedido (400): Tu organización alcanzó el límite de almacenamiento de 1 TB.

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
  },
  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}

Uso y facturación

Las operaciones de la Files API son gratuitas:

• Subir archivos
• Descargar archivos
• Listar archivos
• Obtener metadatos de archivos
• Eliminar archivos

El contenido de archivos usado en solicitudes de Messages se cobra como tokens de entrada.

Límites de velocidad

Las llamadas a la API relacionadas con archivos tienen un “rate limit” (límite de velocidad) de aproximadamente 500 solicitudes por minuto. Para solicitar un límite más alto, contacta a ventas.

Próximos pasos