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 directamente, 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 Messages 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
}

downloadable es false para los archivos que subes. Solo los archivos creados por skills o la herramienta de ejecución de código pueden descargarse. Consulta Descargar un 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",
    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 los tipos de archivo que el bloque document no admite (por ejemplo, .docx y .xlsx), convierte los archivos a texto plano e incluye el contenido directamente en tu mensaje. Los archivos que ya son texto plano, 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.

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",
    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

Recupera una lista de tus archivos subidos. El endpoint está paginado: cada solicitud devuelve hasta limit archivos (20 de forma predeterminada y como máximo 1,000), y el cursor next_page de la respuesta obtiene la página siguiente cuando se pasa de vuelta como el parámetro page. Los archivos se ordenan del más reciente al más antiguo. Consulta la referencia de la API List Files. Los SDKs devuelven la primera página y proporcionan utilidades de paginación automática. El ejemplo de CLI limita el total con --max-items:

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

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 y video 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 workspace en el que se subieron. Cualquier solicitud en el mismo workspace puede hacer referencia a ellos; nunca aceptes IDs de archivo de fuentes no confiables (consulta la advertencia sobre el acceso al workspace)
• Los archivos no pueden modificarse ni renombrarse 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 pueden recuperarse
• 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 los usuarios eliminen se eliminarán de acuerdo con la política de retención de datos de Anthropic. Para conocer la elegibilidad de ZDR en todas las funciones, consulta API y retención de datos

Expiración de archivos

Para que un archivo expire automáticamente, incluye un campo de formulario expires_in_seconds cuando lo subas. 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_at resultante (RFC 3339) aparece en cada respuesta de archivo y es null para los archivos subidos sin expiración. La expiración se establece una sola vez al subir el archivo y no puede cambiarse.

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 haga referencia al archivo falla antes de la inferencia
• Sus metadatos (GET /v1/files/{file_id}) siguen siendo legibles durante hasta 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 aún 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. En los SDKs, llama a client.files en lugar de client.beta.files; mantener client.beta.files funciona solo en las versiones del SDK que ya no envían el encabezado. Las versiones anteriores lo envían desde client.beta.files incluso sin el argumento betas.
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, 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 formas que client.files, con nombres de tipo con el prefijo Beta. Acepta un argumento betas para las funciones de Files que aún 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 formas 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 pueden descargarse. Solo los archivos creados por skills o la herramienta de ejecución de código pueden descargarse
• 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 plano 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

Compatibility