Files API

La Files API te permite subir y gestionar archivos para usar con la API de Claude sin necesidad de volver a subir el contenido en cada solicitud. Esto es especialmente útil cuando se usa la herramienta de ejecución de código para proporcionar entradas (p. ej., conjuntos de datos y documentos) y luego descargar salidas (p. ej., gráficos). También puedes usar la Files API para evitar tener que volver a subir continuamente documentos e imágenes de uso frecuente en múltiples llamadas a la API. Puedes explorar la referencia de la API directamente, además de esta guía.

Modelos compatibles

Referenciar 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 PDFs con todos los modelos Claude 3.5+, y varios otros tipos de archivos para la herramienta de ejecución de código en Claude Haiku 4.5 más todos los modelos Claude 3.7+.

La Files API no es compatible actualmente con Amazon Bedrock ni con Google Vertex AI.

Cómo funciona la Files API

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

• Sube archivos a nuestro almacenamiento seguro y recibe un file_id único
• Descarga archivos que son 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:

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"

La respuesta al subir un archivo incluirá:

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

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-opus-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Please summarize this document for me."
          },
          {
            "type": "document",
            "source": {
              "type": "file",
              "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

Tipos de archivos y bloques de contenido

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

Trabajar con otros formatos de archivo

Para los tipos de archivos 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-opus-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
        }
      ]
    }
  ]
}
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": "Document Title", // Opcional
  "context": "Context about the document", // 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 de un 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 skills o 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 de los archivos

• 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 su eliminación, pero pueden persistir en llamadas activas a la API de Messages y usos de herramientas asociados
• Los archivos que los usuarios eliminen serán eliminados de acuerdo con nuestra política de retención de datos.

Retención de datos

Los archivos subidos a través de la Files API se conservan hasta que se eliminan explícitamente usando el endpoint DELETE /v1/files/{file_id}. Los archivos se almacenan para su reutilización en múltiples solicitudes a la API.

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 (p. ej., usar un archivo de imagen en un bloque de documento)
• Supera el tamaño de la ventana de contexto (400): El archivo es más grande que el tamaño de la ventana de contexto (p. ej., usar un archivo de texto plano de 500 MB en una solicitud /v1/messages)
• Nombre de archivo no válido (400): El nombre de 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 supera el límite de 500 MB
• Límite de almacenamiento superado (403): Tu organización ha alcanzado el límite de almacenamiento de 100 GB

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

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 los archivos usado en solicitudes de Messages se cobra como tokens de entrada. Solo puedes descargar archivos creados por skills o 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