API de Archivos
La API de Archivos te permite subir y gestionar archivos para usar con la API de Anthropic sin tener que volver a subir contenido con cada solicitud. Esto es particularmente útil cuando se utiliza 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). También puedes usar la API de Archivos para evitar tener que volver a subir continuamente documentos e imágenes de uso frecuente en múltiples llamadas a la API.
La API de Archivos está actualmente en beta. Por favor, comunícate a través de nuestro formulario de comentarios para compartir tu experiencia con la API de Archivos.
Modelos compatibles
Hacer referencia a un file_id
en una solicitud de Messages es compatible con todos los modelos que admiten el tipo de archivo dado. Por ejemplo, las imágenes son compatibles con todos los modelos Claude 3+, los PDF en todos los modelos Claude 3.5+, y varios otros tipos de archivos para la herramienta de ejecución de código en Claude 3.5 Haiku y todos los modelos Claude 3.7+.
La API de Archivos actualmente no es compatible con Amazon Bedrock o Google Vertex AI.
Cómo funciona la API de Archivos
La API de Archivos proporciona un enfoque simple de crear una vez, usar muchas veces para trabajar con archivos:
- Sube archivos a nuestro almacenamiento seguro y recibe un
file_id
único - Descarga archivos que son creados desde 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 contenido - Gestiona tus archivos con operaciones de listar, recuperar y eliminar
Cómo usar la API de Archivos
Para usar la API de Archivos, necesitarás incluir el encabezado de función beta: anthropic-beta: files-api-2025-04-14
.
Subir un archivo
Sube un archivo para hacer referencia a él en futuras llamadas a la API:
Tipos de archivos y bloques de contenido
La API de Archivos admite diferentes tipos de archivos que corresponden a diferentes tipos de bloques de contenido:
Tipo de archivo | Tipo MIME | Tipo de bloque de contenido | Caso de uso |
---|---|---|---|
application/pdf | document | Análisis de texto, procesamiento de documentos | |
Texto plano | text/plain | document | Análisis de texto, procesamiento |
Imágenes | image/jpeg , image/png , image/gif , image/webp | image | Análisis de imágenes, tareas visuales |
Conjuntos de datos, otros | Varía | container_upload | Analizar datos, crear visualizaciones |
Bloques de documento
Para PDFs y archivos de texto, usa el bloque de contenido document
:
Bloques de imagen
Para imágenes, usa el bloque de contenido image
:
Gestión de archivos
Listar archivos
Recupera una lista de tus archivos subidos:
Obtener metadatos del archivo
Recupera información sobre un archivo específico:
Eliminar un archivo
Elimina un archivo de tu espacio de trabajo:
Descargar un archivo
Descarga archivos que han sido creados por la herramienta de ejecución de código:
Solo puedes descargar archivos que fueron creados por la herramienta de ejecución de código. Los archivos que subiste no pueden ser descargados.
Almacenamiento de archivos y límites
Límites de almacenamiento
- Tamaño máximo de archivo: 32 MB por archivo
- Almacenamiento total: 100 GB por organización
Ciclo de vida del archivo
- Los archivos están limitados al espacio de trabajo de la clave de API. Otras claves de API pueden usar archivos creados por cualquier otra clave de API asociada con el mismo espacio de trabajo
- Los archivos persisten hasta que los elimines
- Los archivos eliminados no se pueden recuperar
- Los archivos son inaccesibles a través de la API poco después de la eliminación, pero pueden persistir en llamadas activas a la API de
Messages
y usos de herramientas asociados
Manejo de errores
Los errores comunes al usar la API de Archivos 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)
- Archivo demasiado grande (413): El archivo excede el límite de 500 MB
- Límite de almacenamiento excedido (403): Tu organización ha alcanzado el límite de almacenamiento de 100 GB
- 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)
Uso y facturación
Las operaciones de la API de Archivos son gratuitas:
- Subir archivos
- Descargar archivos
- Listar archivos
- Obtener metadatos de archivos
- Eliminar archivos
El contenido de archivos utilizado en solicitudes de Messages
se cobra como tokens de entrada. Solo puedes descargar archivos creados por la herramienta de ejecución de código.
Límites de tasa
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