---
title: Files API
url: https://platform.claude.com/docs/es/build-with-claude/files
description: Sube archivos una sola vez, haz referencia a ellos mediante file_id en las solicitudes de Messages y descarga las salidas creadas por skills o por la herramienta de ejecución de código.
featureMetadata:
  status: ga
  zdr: not-eligible
  supportedPlatforms:
    Claude API: ga
    Claude Platform on AWS: ga
    Microsoft Foundry:
      availability: ga
      note: En [Microsoft Foundry](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry), la API de archivos requiere una [implementación alojada en Anthropic](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
---

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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool) 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](https://platform.claude.com/docs/es/api/files/upload), 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](https://platform.claude.com/docs/es/build-with-claude/vision) son compatibles con todos los modelos actuales de Claude. Para [PDFs](https://platform.claude.com/docs/es/build-with-claude/pdf-support) y [otros tipos de archivo con la herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#compatibility), 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](https://platform.claude.com/docs/es/api/messages/create) usando el `file_id` en lugar de volver a subir el contenido
* **Administra tus archivos** con operaciones de listar, recuperar y eliminar

<Warning id="workspace-scoped-access">
  **Los archivos subidos son accesibles para todo tu workspace (espacio de trabajo), no están limitados a un usuario final, conversación o sesión.** Cualquier clave de API con acceso a un workspace puede acceder a cualquier archivo subido a ese workspace. Cada cuenta de servicio, y cada usuario cuyo rol en la organización permita el acceso a la API, puede usar el Default Workspace además de cualquier workspace al que lo agregues, así que mantén los archivos que deben permanecer separados en su propio [workspace](https://platform.claude.com/docs/es/manage-claude/workspaces#api-keys-and-resource-scoping) y accede a ellos solo con claves limitadas a ese workspace. Nunca aceptes valores de `file_id` de usuarios finales u otras fuentes no confiables: un ID de archivo proporcionado por un usuario permitiría que un usuario de tu aplicación lea contenido que otro usuario subió. Trata los IDs de archivo como referencias del lado del servidor y mantén la correspondencia entre tus usuarios y sus archivos en tu aplicación.

  Si estás creando una aplicación multi-tenant (multiinquilino) sobre la Files API, crea un [workspace](https://platform.claude.com/docs/es/manage-claude/workspaces) separado para cada tenant. El workspace es el límite de aislamiento para los archivos, por lo que un workspace por tenant le da a los datos de cada tenant un aislamiento estricto respecto de todos los demás tenants. Cada organización puede tener hasta 100 workspaces; contacta a tu equipo de cuenta si necesitas más.
</Warning>

## Cómo usar la Files API

### Subir un archivo

Sube un archivo para hacer referencia a él en futuras llamadas a la API:

<CodeGroup>
  ```bash cURL
  curl -X POST https://api.anthropic.com/v1/files \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -F "file=@/path/to/document.pdf"
  ```

  ```bash CLI
  ant files upload --file /path/to/document.pdf
  ```

  ```python Python
  uploaded = client.files.upload(
      file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
  )
  file_id = uploaded.id
  print(file_id)
  ```

  ```typescript TypeScript
  const uploaded = await client.files.upload({
    file: await toFile(fs.createReadStream("/path/to/document.pdf"), undefined, {
      type: "application/pdf"
    })
  });
  console.log(uploaded.id);
  ```

  ```csharp C#
  var uploaded = await client.Files.Upload(
      new FileUploadParams
      {
          File = new BinaryContent
          {
              Stream = File.OpenRead("/path/to/document.pdf"),
              FileName = "document.pdf",
              ContentType = new("application/pdf")
          }
      });

  var fileId = uploaded.ID;
  Console.WriteLine(fileId);
  ```

  ```go Go
  f, err := os.Open("/path/to/document.pdf")
  if err != nil {
  	log.Fatal(err)
  }
  defer f.Close()

  response, err := client.Files.Upload(context.Background(),
  	anthropic.FileUploadParams{
  		File: anthropic.File(f, "document.pdf", "application/pdf"),
  	})
  if err != nil {
  	log.Fatal(err)
  }

  fileID := response.ID
  fmt.Println(fileID)
  ```

  ```java Java
  FileMetadata file = client.files().upload(
      FileUploadParams.builder()
          .file(MultipartField.<InputStream>builder()
              .value(Files.newInputStream(Path.of("/path/to/document.pdf")))
              .filename("document.pdf")
              .contentType("application/pdf")
              .build())
          .build()
  );

  String fileId = file.id();
  System.out.println(fileId);
  ```

  ```php PHP
  $file = $client->files->upload(
      file: FileParam::fromResource(fopen('/path/to/document.pdf', 'rb'), contentType: 'application/pdf'),
  );

  $fileId = $file->id;
  echo $fileId;
  ```

  ```ruby Ruby
  file = client.files.upload(
    file: Anthropic::FilePart.new(
      Pathname("/path/to/document.pdf"),
      content_type: "application/pdf"
    )
  )

  file_id = file.id
  puts file_id
  ```
</CodeGroup>

La respuesta al subir un archivo incluye:

```json Response
{
  "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](https://platform.claude.com/docs/es/build-with-claude/skills-guide) o la [herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool) pueden descargarse. Consulta [Descargar un archivo](https://platform.claude.com/docs/es/build-with-claude/files#downloading-a-file).

### Usar un archivo en mensajes

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

<CodeGroup>
  ```bash cURL
  curl -X POST https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-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"'"
              }
            }
          ]
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create <<YAML
  model: claude-opus-5-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
  YAML
  ```

  ```python Python
  response = client.messages.create(
      model="claude-opus-5-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)
  ```

  ```typescript TypeScript
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: "Please summarize this document for me."
          },
          {
            type: "document",
            source: {
              type: "file",
              file_id: uploaded.id
            }
          }
        ]
      }
    ]
  });

  console.log(response);
  ```

  ```csharp C#
  var response = await client.Messages.Create(
      new MessageCreateParams
      {
          Model = Model.ClaudeOpus5_5,
          MaxTokens = 1024,
          Messages =
          [
              new MessageParam
              {
                  Role = Role.User,
                  Content = new List<ContentBlockParam>
                  {
                      new TextBlockParam { Text = "Please summarize this document for me." },
                      new DocumentBlockParam
                      {
                          Source = new FileDocumentSource { FileID = fileId }
                      }
                  }
              }
          ]
      });

  Console.WriteLine(response);
  ```

  ```go Go
  msg, err := client.Messages.New(context.Background(),
  	anthropic.MessageNewParams{
  		Model:     anthropic.ModelClaudeOpus5_5,
  		MaxTokens: 1024,
  		Messages: []anthropic.MessageParam{
  			anthropic.NewUserMessage(
  				anthropic.NewTextBlock("Please summarize this document for me."),
  				anthropic.NewDocumentBlock(anthropic.FileDocumentSourceParam{
  					FileID: fileID,
  				}),
  			),
  		},
  	})
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(msg)
  ```

  ```java Java
  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(1024)
      .addUserMessageOfBlockParams(List.of(
          ContentBlockParam.ofText(TextBlockParam.builder()
              .text("Please summarize this document for me.")
              .build()),
          ContentBlockParam.ofDocument(DocumentBlockParam.builder()
              .fileSource(fileId)
              .build())
      ))
      .build();

  Message message = client.messages().create(params);
  System.out.println(message);
  ```

  ```php PHP
  $response = $client->messages->create(
      maxTokens: 1024,
      messages: [
          [
              'role' => 'user',
              'content' => [
                  ['type' => 'text', 'text' => 'Please summarize this document for me.'],
                  [
                      'type' => 'document',
                      'source' => [
                          'type' => 'file',
                          'fileID' => $fileId,
                      ],
                  ],
              ],
          ],
      ],
      model: 'claude-opus-5-5',
  );

  echo $response;
  ```

  ```ruby Ruby
  response = client.messages.create(
    model: "claude-opus-5-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
            }
          }
        ]
      }
    ]
  )

  puts response
  ```
</CodeGroup>

### Tipos de archivo y bloques de contenido

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

| Tipo de archivo                                                                                                                                  | Tipo MIME                                            | Tipo de bloque de contenido | Caso de uso                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | --------------------------- | ---------------------------------------------- |
| PDF                                                                                                                                              | `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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) | Varía                                                | `container_upload`          | Analizar datos, crear visualizaciones          |

#### Bloques de documento

Para PDFs y archivos de texto, usa el bloque de contenido `document`:

```json
{
  "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`:

```json
{
  "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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files), usa el bloque de contenido `container_upload`:

```json
{
  "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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) usando un bloque `container_upload`.

Los siguientes ejemplos leen un archivo de texto y envían su contenido como texto plano:

<CodeGroup>
  ```bash cURL
  # Lee el archivo de texto
  # Nota: para archivos con caracteres especiales, considera usar codificación base64
  TEXT_CONTENT=$(cat document.txt)

  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-5-5",
    "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
  ```

  ```bash CLI
  # La referencia "@./path" inserta el contenido del archivo directamente en el campo.
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 1024 \
    --transform 'content.#(type=="text").text' \
    --raw-output <<'YAML'
  messages:
    - role: user
      content:
        - type: text
          text: "Here's the document content:"
        - type: text
          text: "@./document.txt"
        - type: text
          text: "Please summarize this document."
  YAML
  ```

  ```python Python
  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-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)
  ```

  ```typescript TypeScript
  import fs from "node:fs/promises";
  // ...
  const client = new Anthropic();

  // Lee el archivo de texto
  const textContent = await fs.readFile("document.txt", "utf-8");

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: `Here's the document content:\n\n${textContent}\n\nPlease summarize this document.`
          }
        ]
      }
    ]
  });

  const textBlock = response.content.find(
    (block): block is Anthropic.TextBlock => block.type === "text"
  );
  console.log(textBlock?.text);
  ```

  ```csharp C#
  AnthropicClient client = new();

  // Lee el archivo de texto
  string textContent = await File.ReadAllTextAsync("document.txt");

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 1024,
      Messages = [new()
      {
          Role = Role.User,
          Content = $"Here's the document content:\n\n{textContent}\n\nPlease summarize this document."
      }]
  };

  var message = await client.Messages.Create(parameters);
  foreach (var block in message.Content)
  {
      if (block.TryPickText(out var textBlock))
      {
          Console.WriteLine(textBlock.Text);
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  // Lee el archivo de texto
  textContent, err := os.ReadFile("document.txt")
  if err != nil {
  	log.Fatal(err)
  }

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock(
  			fmt.Sprintf("Here's the document content:\n\n%s\n\nPlease summarize this document.", string(textContent)),
  		)),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  for _, block := range response.Content {
  	if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
  		fmt.Println(textBlock.Text)
  	}
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  // Lee el archivo de texto
  String textContent = Files.readString(Path.of("document.txt"));

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(1024L)
      .addUserMessage("Here's the document content:\n\n" + textContent + "\n\nPlease summarize this document.")
      .build();

  Message response = client.messages().create(params);
  response.content().stream()
      .flatMap(block -> block.text().stream())
      .forEach(textBlock -> System.out.println(textBlock.text()));
  ```

  ```php PHP
  $client = new Client();

  // Lee el archivo de texto
  $textContent = file_get_contents("document.txt");

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [
          [
              'role' => 'user',
              'content' => [
                  [
                      'type' => 'text',
                      'text' => "Here's the document content:\n\n{$textContent}\n\nPlease summarize this document."
                  ]
              ]
          ]
      ],
      model: 'claude-opus-5-5',
  );

  foreach ($message->content as $block) {
      if ($block->type === 'text') {
          echo $block->text, PHP_EOL;
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # Lee el archivo de texto
  text_content = File.read("document.txt")

  message = client.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: "Here's the document content:\n\n#{text_content}\n\nPlease summarize this document."
          }
        ]
      }
    ]
  )

  message.content.each do |block|
    puts block.text if block.type == :text
  end
  ```
</CodeGroup>

<Note>
  Para archivos .docx que contienen imágenes, conviértelos primero a formato PDF y luego usa la [compatibilidad con PDF](https://platform.claude.com/docs/es/build-with-claude/pdf-support) para aprovechar el análisis de imágenes integrado. Esto permite usar citas del documento PDF.
</Note>

### 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 vuelve a pasar 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](https://platform.claude.com/docs/es/api/files/list). El SDK devuelve la primera página y proporciona utilidades de [paginación automática](https://platform.claude.com/docs/es/api/overview#pagination). El ejemplo de la CLI limita el total con `--max-items`:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/files \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01"
  ```

  ```bash CLI
  ant files list --max-items 10
  ```

  ```python Python
  client = anthropic.Anthropic()
  files = client.files.list()
  print(files)
  ```

  ```typescript TypeScript
  const client = new Anthropic();
  const files = await client.files.list();
  console.log(files);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var files = await client.Files.List();
  Console.WriteLine(files);
  ```

  ```go Go
  client := anthropic.NewClient()

  files, err := client.Files.List(context.TODO(), anthropic.FileListParams{})
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(files)
  ```

  ```java Java
  import com.anthropic.models.files.FileListPage;
  // ...
  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      FileListPage files = client.files().list();
      System.out.println(files);
  }
  ```

  ```php PHP
  $client = new Client();

  $files = $client->files->list();
  echo $files;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  files = client.files.list
  puts files
  ```
</CodeGroup>

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:

<CodeGroup>
  ```bash cURL
  curl "https://api.anthropic.com/v1/files/$FILE_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01"
  ```

  ```bash CLI
  ant files retrieve-metadata \
    --file-id "$FILE_ID"
  ```

  ```python Python
  file = client.files.retrieve_metadata(file_id)
  print(file)
  ```

  ```typescript TypeScript
  const file = await client.files.retrieveMetadata(uploaded.id);
  console.log(file);
  ```

  ```csharp C#
  var file = await client.Files.RetrieveMetadata(fileId);
  Console.WriteLine(file);
  ```

  ```go Go
  metadata, err := client.Files.GetMetadata(context.TODO(), fileID, anthropic.FileGetMetadataParams{})
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(metadata)
  ```

  ```java Java
  FileMetadata metadata = client.files().retrieveMetadata(fileId);

  System.out.println(metadata);
  ```

  ```php PHP
  $file = $client->files->retrieveMetadata($fileId);
  echo $file;
  ```

  ```ruby Ruby
  file = client.files.retrieve_metadata(file_id)
  puts file
  ```
</CodeGroup>

#### Eliminar un archivo

Elimina un archivo de tu workspace:

<CodeGroup>
  ```bash cURL
  curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01"
  ```

  ```bash CLI
  ant files delete \
    --file-id "$FILE_ID"
  ```

  ```python Python
  client.files.delete(file_id)
  ```

  ```typescript TypeScript
  await client.files.delete(uploaded.id);
  ```

  ```csharp C#
  await client.Files.Delete(fileId);
  ```

  ```go Go
  _, err = client.Files.Delete(context.TODO(), fileID, anthropic.FileDeleteParams{})
  if err != nil {
  	log.Fatal(err)
  }
  ```

  ```java Java
  client.files().delete(fileId);
  ```

  ```php PHP
  $client->files->delete($fileId);
  ```

  ```ruby Ruby
  client.files.delete(file_id)
  ```
</CodeGroup>

### Descargar un archivo

Descarga archivos que fueron creados por [skills](https://platform.claude.com/docs/es/build-with-claude/skills-guide) o la [herramienta de ejecución de código](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool). 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`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files) de la respuesta de Messages que lo creó:

<CodeGroup>
  ```bash cURL
  curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/content" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    --output downloaded_file.txt
  ```

  ```bash CLI
  ant files download \
    --file-id "$FILE_ID" \
    --output downloaded_file.txt
  ```

  ```python Python
  file_content = client.files.download(file_id)

  file_content.write_to_file("downloaded_file.txt")
  ```

  ```typescript TypeScript
  const content = await client.files.download(uploaded.id);

  const bytes = Buffer.from(await content.arrayBuffer());
  await fsp.writeFile("downloaded_file.txt", bytes);
  ```

  ```csharp C#
  using var fileContent = await client.Files.Download(fileId);
  await using var source = await fileContent.ReadAsStream();
  await using var destination = File.Create("downloaded_file.txt");
  await source.CopyToAsync(destination);
  ```

  ```go Go
  func downloadFile(client anthropic.Client, fileID string) error {
  	resp, err := client.Files.Download(context.TODO(), fileID, anthropic.FileDownloadParams{})
  	if err != nil {
  		return err
  	}
  	defer resp.Body.Close()

  	out, err := os.Create("downloaded_file.txt")
  	if err != nil {
  		return err
  	}
  	defer out.Close()

  	_, err = io.Copy(out, resp.Body)
  	return err
  }
  ```

  ```java Java
  try (HttpResponse response = client.files().download(fileId)) {
      try (InputStream body = response.body()) {
          Files.copy(body, Path.of("downloaded_file.txt"),
              StandardCopyOption.REPLACE_EXISTING);
      }
  }
  ```

  ```php PHP
  $fileContent = $client->files->download($fileId);

  file_put_contents('downloaded_file.txt', $fileContent);
  ```

  ```ruby Ruby
  file_content = client.files.download(file_id)

  File.binwrite("downloaded_file.txt", file_content.read)
  ```
</CodeGroup>

<Note>
  Un archivo es descargable solo cuando sus metadatos muestran `"downloadable": true`, lo cual ocurre con los archivos creados por skills o la herramienta de ejecución de código. Descargar un archivo que subiste devuelve un error 400.
</Note>

En la Claude API, los archivos de imagen, video y audio 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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#content-credentials-on-generated-files) 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](https://platform.claude.com/docs/es/build-with-claude/files#workspace-scoped-access))
* 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](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data) de Anthropic. Para conocer la elegibilidad de ZDR en todas las funciones, consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention)

### 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.

<Note>
  La expiración es una función de ciclo de vida, no un control de eliminación garantizada. Después de `expires_at`, el contenido del archivo ya no puede recuperarse a través de la API y se libera de tu cuota de almacenamiento; el contenido subyacente puede conservarse durante un período limitado posterior para revisión de seguridad antes de su eliminación permanente, y los metadatos del archivo permanecen visibles durante hasta 30 días después de la expiración. Para eliminar un archivo antes de su expiración programada, usa `DELETE /v1/files/{file_id}`.
</Note>

### Registro de auditoría

Si tu organización tiene habilitada la [Compliance API](https://platform.claude.com/docs/es/manage-claude/compliance-api), su [Activity Feed](https://platform.claude.com/docs/es/manage-claude/compliance-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](https://platform.claude.com/docs/es/manage-claude/compliance-api-access) antes de depender de este registro de auditoría. En [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws#monitoring-and-logging), 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:

|                                               | Con `files-api-2025-04-14`              | Sin el encabezado                                                                      |
| --------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------- |
| Respuesta de listado                          | `{ data, has_more, first_id, last_id }` | `{ data, next_page }`; pasa `next_page` de vuelta como el parámetro de consulta `page` |
| Cursores de listado                           | `before_id`, `after_id`                 | `page`, o hasta 100 `ids[]` (`before_id` y `after_id` devuelven un error 400)          |
| `expires_at` en objetos de archivo            | No se devuelve                          | Siempre presente; `null` cuando el archivo no tiene expiración                         |
| `Content-Type` en la parte del archivo subido | Obligatorio                             | Opcional; el tipo se detecta cuando se omite                                           |

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](https://platform.claude.com/docs/es/build-with-claude/files#sdk-beta-namespace). 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](https://platform.claude.com/docs/es/build-with-claude/files#managing-files).
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](https://platform.claude.com/docs/es/build-with-claude/files#file-expiration)).

### 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](https://platform.claude.com/docs/es/managed-agents/files). 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

```json Output
{
  "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](mailto:sales@anthropic.com).

## Próximos pasos

<CardGroup cols={3}>
  <Card title="Compatibilidad con PDF" icon="file" href="https://platform.claude.com/docs/es/build-with-claude/pdf-support">
    Procesa PDFs con Claude. Extrae texto, analiza gráficos y comprende el contenido visual de tus documentos.
  </Card>

  <Card title="Herramienta de ejecución de código" icon="terminal" href="https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool">
    Ejecuta código Python y bash en un contenedor aislado para analizar datos, generar archivos e iterar sobre soluciones.
  </Card>

  <Card title="Visión" icon="image" href="https://platform.claude.com/docs/es/build-with-claude/vision">
    Procesa y analiza entradas visuales y genera texto y código a partir de imágenes.
  </Card>
</CardGroup>