Files API

La Files API te permite subir y gestionar archivos para usarlos con la API de Claude sin tener que volver a subir el contenido en 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 resultados (por ejemplo, gráficos). Puedes explorar la referencia de la API directamente, además de esta guía.



Compatibilidad con tipos de archivo

Referenciar un file_id en una solicitud de Messages es compatible con todos los modelos que admiten el tipo de archivo en cuestión. 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 ver 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
• Referencia archivos en solicitudes de Messages usando el file_id en lugar de volver a subir el contenido
• Gestiona tus archivos con operaciones de listar, recuperar y eliminar



Cómo usar la Files API



Subir un archivo

Sube un archivo para referenciarlo en futuras llamadas a la API:

uploaded = client.beta.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
}

downloadable es false para los archivos que subes. Solo los archivos creados por skills o la herramienta de ejecución de código se pueden descargar. Consulta Descargar un archivo.



Usar un archivo en mensajes

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

response = client.beta.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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
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 de 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 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)



Gestionar archivos



Listar archivos

Recupera una lista de tus archivos subidos. El endpoint está paginado: cada solicitud devuelve hasta limit archivos (20 por defecto), y los parámetros before_id y after_id obtienen la página adyacente. Consulta la referencia de la API List Files. Los SDKs devuelven la primera página y proporcionan helpers de paginación automática. El ejemplo de CLI limita el total con --max-items:

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



Obtener metadatos de archivo

Recupera información sobre un archivo específico:

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



Eliminar un archivo

Elimina un archivo de tu workspace:

client.beta.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 se pueden descargar. 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.beta.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")



Almacenamiento de archivos y límites



Límites de almacenamiento

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



Ciclo de vida de los archivos

• Los archivos están limitados al workspace de la clave de API que los subió. Cualquier clave de API en el mismo workspace puede referenciarlos; nunca aceptes IDs de archivo de fuentes no confiables (consulta la advertencia de acceso al workspace)
• 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 elimines con el endpoint DELETE /v1/files/{file_id}
• Los archivos eliminados no se pueden recuperar
• Los archivos son inaccesibles a través de la API poco después de su eliminación, pero pueden persistir en llamadas activas a la Messages API y 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 la elegibilidad de ZDR en todas las funciones, consulta API y retención de datos



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 los archivos creados por skills o la herramienta de ejecución de código se pueden descargar
• Excede el tamaño de la ventana de contexto (400): El archivo es más grande que el tamaño de la ventana de contexto (por ejemplo, usar un archivo de texto plano de 500 MB en una solicitud /v1/messages)
• Nombre de archivo no válido (400): El nombre del archivo no cumple con 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 ha alcanzado el límite de almacenamiento de 500 GB

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

Durante el período beta:

• Las llamadas a la API relacionadas con archivos están limitadas a aproximadamente 100 solicitudes por minuto
• Contáctanos si necesitas límites más altos para tu caso de uso



Próximos pasos