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 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). También puedes usar la API de Archivos para evitar tener que volver a subir continuamente documentos e imágenes utilizados frecuentemente a través de múltiples llamadas a la API.

​

Modelos compatibles

Referenciar un file_id en una solicitud de Messages es compatible con todos los modelos que soportan el tipo de archivo dado. Por ejemplo, las imágenes son compatibles con todos los modelos Claude 3+, los PDFs en todos los modelos Claude 3.5+, y varios otros tipos de archivo para la herramienta de ejecución de código en Claude 3.5 Haiku más 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:

• Subir archivos a nuestro almacenamiento seguro y recibir un file_id único
• Descargar archivos que son creados por la herramienta de ejecución de código
• Referenciar archivos en solicitudes de Messages usando el file_id en lugar de volver a subir contenido
• Gestionar tus archivos con operaciones de listar, recuperar y eliminar

​

Cómo usar la API de Archivos

​

Subir un archivo

Sube un archivo para ser referenciado en futuras llamadas a la API:

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@/path/to/document.pdf"

​

Usar un archivo en mensajes

Una vez subido, referencia el archivo usando su file_id:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Por favor, resume este documento para mí."          
          },
          {
            "type": "document",
            "source": {
              "type": "file",
              "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

​

Tipos de archivo y bloques de contenido

La API de Archivos soporta diferentes tipos de archivo que corresponden a diferentes tipos de bloques de contenido:

​

Trabajar con otros formatos de archivo

Para tipos de archivo que no son compatibles como bloques document (.csv, .txt, .md, .docx, .xlsx), convierte los archivos a texto plano e incluye el contenido directamente en tu mensaje:

# Ejemplo: Leer un archivo de texto y enviarlo como texto plano
# Nota: Para archivos con caracteres especiales, considera la codificación base64
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<EOF
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Aquí está el contenido del documento:\n\n${TEXT_CONTENT}\n\nPor favor, resume este documento."
        }
      ]
    }
  ]
}
EOF

​

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": "Título del Documento", // Opcional
  "context": "Contexto sobre el documento", // Opcional  
  "citations": {"enabled": true} // Opcional, habilita las citas
}

​

Bloques de imagen

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

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

​

Gestionar archivos

​

Listar archivos

Recupera una lista de tus archivos subidos:

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​

Obtener metadatos del archivo

Recupera información sobre un archivo específico:

curl https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​

Eliminar un archivo

Elimina un archivo de tu espacio de trabajo:

curl -X DELETE https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

​

Descargar un archivo

Descarga archivos que han sido creados por la herramienta de ejecución de código:

curl -X GET "https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output 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: 100 GB por organización

​

Ciclo de vida del archivo

• Los archivos están limitados al espacio de trabajo de la clave API. Otras claves API pueden usar archivos creados por cualquier otra clave 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 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 invá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)
• 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 invá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 (403): Tu organización ha alcanzado el límite de almacenamiento de 100 GB

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Archivo no encontrado: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

​

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 usado en solicitudes Messages se factura como tokens de entrada. Solo puedes descargar archivos creados por la herramienta de ejecución de código.

​

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