---
title: Files API
url: https://platform.claude.com/docs/pt-BR/build-with-claude/files
description: Faça upload de arquivos uma vez, referencie-os por file_id em requisições Messages e baixe saídas criadas por skills ou pela ferramenta de execução de código.
featureMetadata:
  status: ga
  zdr: not-eligible
  supportedPlatforms:
    Claude API: ga
    Claude Platform on AWS: ga
    Microsoft Foundry:
      availability: ga
      note: No [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry), a Files API requer uma [implantação Hosted on Anthropic](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
---

A Files API permite que você faça upload e gerencie arquivos para usar com a Claude API sem precisar reenviar o conteúdo a cada requisição. Isso é particularmente útil ao usar a [ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool) para fornecer entradas (por exemplo, conjuntos de dados e documentos) e depois baixar saídas (por exemplo, gráficos). Você pode [explorar a referência da API diretamente](https://platform.claude.com/docs/pt-BR/api/files/upload), além deste guia.

## Suporte a tipos de arquivo

Referenciar um `file_id` em uma requisição de Messages é suportado em todos os modelos que suportam o tipo de arquivo em questão. [Imagens](https://platform.claude.com/docs/pt-BR/build-with-claude/vision) são suportadas em todos os modelos Claude atuais. Para [PDFs](https://platform.claude.com/docs/pt-BR/build-with-claude/pdf-support) e [outros tipos de arquivo com a ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#compatibility), consulte as páginas vinculadas para ver o suporte por modelo.

## Como a Files API funciona

A Files API oferece uma abordagem de criar uma vez e usar muitas vezes para trabalhar com arquivos:

* **Faça upload de arquivos** para o armazenamento seguro da Anthropic e receba um `file_id` exclusivo
* **Baixe arquivos** que são criados por skills ou pela ferramenta de execução de código
* **Referencie arquivos** em requisições de [Messages](https://platform.claude.com/docs/pt-BR/api/messages/create) usando o `file_id` em vez de reenviar o conteúdo
* **Gerencie seus arquivos** com operações de listar, recuperar e excluir

<Warning id="workspace-scoped-access">
  **Os arquivos enviados são acessíveis a todo o seu workspace, não têm escopo restrito a um usuário final, conversa ou sessão.** Qualquer chave de API com acesso a um workspace pode acessar quaisquer arquivos enviados para esse workspace. Toda conta de serviço, e todo usuário cuja função na organização permita acesso à API, pode usar o Default Workspace além de qualquer workspace ao qual você o adicione; portanto, mantenha arquivos que precisam ficar separados em seu próprio [workspace](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces#api-keys-and-resource-scoping) e acesse-os apenas com chaves com escopo para esse workspace. Nunca aceite valores de `file_id` de usuários finais ou de outras fontes não confiáveis: um ID de arquivo fornecido pelo usuário permitiria que um usuário da sua aplicação lesse conteúdo que outro usuário enviou. Trate os IDs de arquivo como referências do lado do servidor e mantenha o mapeamento entre seus usuários e os arquivos deles na sua aplicação.

  Se você está construindo uma aplicação multi-tenant (multilocatária) sobre a Files API, crie um [workspace](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces) separado para cada tenant. O workspace é a fronteira de isolamento para arquivos, então um workspace por tenant dá aos dados de cada tenant um isolamento rígido em relação a todos os outros tenants. Cada organização pode ter até 100 workspaces; entre em contato com sua equipe de conta se precisar de mais.
</Warning>

## Como usar a Files API

### Fazendo upload de um arquivo

Faça upload de um arquivo para ser referenciado em chamadas futuras à 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>

A resposta do upload de um arquivo inclui:

```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` é `false` para arquivos que você envia. Somente arquivos criados por [skills](https://platform.claude.com/docs/pt-BR/build-with-claude/skills-guide) ou pela [ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool) podem ser baixados. Consulte [Baixando um arquivo](https://platform.claude.com/docs/pt-BR/build-with-claude/files#downloading-a-file).

### Usando um arquivo em mensagens

Após o upload, referencie o arquivo passando o `id` da resposta de upload 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 arquivo e blocos de conteúdo

A Files API suporta diferentes tipos de arquivo que correspondem a diferentes tipos de bloco de conteúdo:

| Tipo de arquivo                                                                                                                                      | Tipo MIME                                            | Tipo de bloco de conteúdo | Caso de uso                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------- | --------------------------------------------- |
| PDF                                                                                                                                                  | `application/pdf`                                    | `document`                | Análise de texto, processamento de documentos |
| Texto simples                                                                                                                                        | `text/plain`                                         | `document`                | Análise de texto, processamento               |
| Imagens                                                                                                                                              | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image`                   | Análise de imagens, tarefas visuais           |
| [Conjuntos de dados, outros](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) | Varia                                                | `container_upload`        | Analisar dados, criar visualizações           |

#### Blocos de documento

Para PDFs e arquivos de texto, use o bloco de conteúdo `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
}
```

#### Blocos de imagem

Para imagens, use o bloco de conteúdo `image`:

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

#### Blocos de upload para contêiner

Para enviar um arquivo à [ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files), use o bloco de conteúdo `container_upload`:

```json
{
  "type": "container_upload",
  "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}
```

### Trabalhando com outros formatos de arquivo

Para tipos de arquivo que o bloco `document` não suporta (por exemplo, .docx e .xlsx), converta os arquivos para texto simples e inclua o conteúdo diretamente na sua mensagem. Arquivos que já são texto simples, como arquivos .csv e .md, podem ser lidos dessa forma ou enviados pela Files API com um tipo de conteúdo `text/plain` explícito. Para analisar conjuntos de dados em vez de lê-los como texto, faça upload deles para a [ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) usando um bloco `container_upload`.

Os exemplos a seguir leem um arquivo de texto e enviam seu conteúdo como texto simples:

<CodeGroup>
  ```bash cURL
  # Lê o arquivo de texto
  # Observação: para arquivos com caracteres especiais, considere usar codificação 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
  # A referência "@./path" insere o conteúdo do arquivo diretamente no 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()

  # Lê o arquivo 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();

  // Lê o arquivo 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();

  // Lê o arquivo 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()

  // Lê o arquivo 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();

  // Lê o arquivo 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();

  // Lê o arquivo 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

  # Lê o arquivo 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 arquivos .docx contendo imagens, converta-os primeiro para o formato PDF e depois use o [suporte a PDF](https://platform.claude.com/docs/pt-BR/build-with-claude/pdf-support) para aproveitar a análise de imagens integrada. Isso permite usar citações do documento PDF.
</Note>

### Gerenciando arquivos

#### Listar arquivos

Recupere uma lista dos seus arquivos enviados. O endpoint é paginado: cada requisição retorna até `limit` arquivos (20 por padrão e no máximo 1.000), e o cursor `next_page` da resposta busca a próxima página quando passado de volta como o parâmetro `page`. Os arquivos são ordenados do mais recente para o mais antigo. Consulte a [referência da API List Files](https://platform.claude.com/docs/pt-BR/api/files/list). O SDK retorna a primeira página e fornece auxiliares de [paginação automática](https://platform.claude.com/docs/pt-BR/api/overview#pagination). O exemplo da CLI limita o total com `--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 um conjunto conhecido de arquivos em uma única requisição em vez de paginar, passe até 100 IDs de arquivo como parâmetros de consulta `ids[]`. Uma requisição com `ids[]` sempre retorna uma única página (`next_page` é `null`), e qualquer ID que não corresponda a um arquivo no seu workspace é silenciosamente omitido de `data`; compare os IDs retornados com os IDs solicitados para detectar ausências. `ids[]` não pode ser combinado com `page` ou `limit`.

#### Obter metadados do arquivo

Recupere informações sobre um arquivo 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>

#### Excluir um arquivo

Remova um arquivo do seu 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>

### Baixando um arquivo

Baixe arquivos que foram criados por [skills](https://platform.claude.com/docs/pt-BR/build-with-claude/skills-guide) ou pela [ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool). Arquivos que você envia não podem ser baixados. O `file_id` de um arquivo gerado aparece no [bloco de conteúdo `bash_code_execution_tool_result`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files) da resposta de Messages que o criou:

<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>
  Um arquivo só pode ser baixado quando seus metadados mostram `"downloadable": true`, o que é o caso de arquivos criados por skills ou pela ferramenta de execução de código. Baixar um arquivo que você enviou retorna um erro 400.
</Note>

Na Claude API, os arquivos de imagem, vídeo e áudio suportados que Claude produz com a ferramenta de execução de código, incluindo arquivos criados por skills, trazem Content Credentials C2PA assinadas quando você os baixa. Consulte [Content Credentials em arquivos gerados](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#content-credentials-on-generated-files) para saber o que a credencial contém e como verificá-la.

## Armazenamento de arquivos e limites

### Limites de armazenamento

* **Tamanho máximo de arquivo:** 500 MB por arquivo
* **Armazenamento total:** 1 TB por organização

### Ciclo de vida dos arquivos

* Os arquivos têm escopo restrito ao workspace em que foram enviados. Qualquer requisição no mesmo workspace pode referenciá-los; nunca aceite IDs de arquivo de fontes não confiáveis (consulte o [aviso sobre acesso ao workspace](https://platform.claude.com/docs/pt-BR/build-with-claude/files#workspace-scoped-access))
* Os arquivos não podem ser modificados ou renomeados após o upload. Para alterar o conteúdo de um arquivo, faça upload de um novo arquivo e exclua o antigo
* Os arquivos persistem até que você os exclua com o endpoint `DELETE /v1/files/{file_id}` ou até atingirem seu `expires_at`
* Arquivos excluídos não podem ser recuperados
* Os arquivos ficam inacessíveis pela API pouco depois da exclusão, mas podem persistir em chamadas ativas à Messages API e nos usos de ferramentas associados
* Arquivos que os usuários excluem serão excluídos de acordo com a [política de retenção de dados](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data) da Anthropic. Para elegibilidade a ZDR em todos os recursos, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention)

### Expiração de arquivos

Para que um arquivo expire automaticamente, inclua um campo de formulário `expires_in_seconds` ao fazer o upload. O valor é um número inteiro de segundos entre 3.600 (1 hora) e 7.776.000 (90 dias). O timestamp `expires_at` resultante (RFC 3339) aparece em toda resposta de arquivo e é `null` para arquivos enviados sem expiração. A expiração é definida uma única vez no upload e não pode ser alterada.

Quando um arquivo atinge seu `expires_at`:

* Baixar seu conteúdo (`GET /v1/files/{file_id}/content`) retorna um erro 404
* Uma requisição de Messages que referencia o arquivo falha antes da inferência
* Seus metadados (`GET /v1/files/{file_id}`) permanecem legíveis por até 30 dias, com `expires_at` no passado
* Ele continua aparecendo nas respostas de listagem durante essa janela; compare `expires_at` com o horário atual para filtrar arquivos expirados

Excluir um arquivo expirado com `DELETE /v1/files/{file_id}` remove seus metadados imediatamente em vez de aguardar o término da janela de 30 dias.

<Note>
  A expiração é um recurso de ciclo de vida, não um controle de exclusão garantida. Após `expires_at`, o conteúdo do arquivo não pode mais ser recuperado pela API e é liberado da sua cota de armazenamento; o conteúdo subjacente pode ser retido por um período limitado depois disso para revisão de segurança antes da exclusão permanente, e os metadados do arquivo permanecem visíveis por até 30 dias após a expiração. Para remover um arquivo antes da expiração programada, use `DELETE /v1/files/{file_id}`.
</Note>

### Registro de auditoria

Se sua organização tem a [Compliance API](https://platform.claude.com/docs/pt-BR/manage-claude/compliance-api) habilitada, seu [Activity Feed](https://platform.claude.com/docs/pt-BR/manage-claude/compliance-activity-feed) registra as operações da Files API feitas com uma chave de API da Claude API ou a partir do Claude Console: cada upload (`POST /v1/files`), download de conteúdo (`GET /v1/files/{file_id}/content`) e exclusão (`DELETE /v1/files/{file_id}`) aparece como uma atividade `platform_file_uploaded`, `platform_file_content_downloaded` ou `platform_file_deleted`. A listagem de arquivos e a recuperação de metadados de arquivos não são registradas. Operações que ocorrem enquanto a Compliance API está desativada não são registradas e não podem ser recuperadas posteriormente, portanto [configure a Compliance API](https://platform.claude.com/docs/pt-BR/manage-claude/compliance-api-access) antes de depender dessa trilha de auditoria. No [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws#monitoring-and-logging), audite as operações de arquivo com eventos de dados do AWS CloudTrail.

## Migrar de `files-api-2025-04-14`

A Files API saiu da fase beta e não precisa de cabeçalho beta. Migrar de `files-api-2025-04-14` é opcional: requisições que ainda o enviam continuam funcionando e continuam retornando os formatos de resposta beta, então uma integração existente continua funcionando até que você a altere. Remover o cabeçalho muda essas requisições para os formatos documentados nesta página:

|                                            | Com `files-api-2025-04-14`              | Sem o cabeçalho                                                                       |
| ------------------------------------------ | --------------------------------------- | ------------------------------------------------------------------------------------- |
| Resposta de listagem                       | `{ data, has_more, first_id, last_id }` | `{ data, next_page }`; passe `next_page` de volta como o parâmetro de consulta `page` |
| Cursores de listagem                       | `before_id`, `after_id`                 | `page`, ou até 100 `ids[]` (`before_id` e `after_id` retornam um erro 400)            |
| `expires_at` em objetos de arquivo         | Não retornado                           | Sempre presente; `null` quando o arquivo não tem expiração                            |
| `Content-Type` na parte do arquivo enviado | Obrigatório                             | Opcional; o tipo é detectado quando omitido                                           |

Para migrar:

1. **Remova o cabeçalho beta.** Retire `anthropic-beta: files-api-2025-04-14` das suas requisições. Nos SDKs, chame `client.files` em vez de `client.beta.files`; manter `client.beta.files` funciona apenas nas [versões do SDK que não enviam mais o cabeçalho](https://platform.claude.com/docs/pt-BR/build-with-claude/files#sdk-beta-namespace). Versões anteriores o enviam a partir de `client.beta.files` mesmo sem o argumento `betas`.
2. **Atualize a paginação.** Substitua os loops com `after_id`/`before_id` pelo cursor `page`/`next_page`, ou use os auxiliares de paginação automática do SDK mostrados em [Gerenciando arquivos](https://platform.claude.com/docs/pt-BR/build-with-claude/files#managing-files).
3. **Leia `expires_at`.** O campo aparece apenas sem o cabeçalho; `null` significa que o arquivo não tem expiração (consulte [Expiração de arquivos](https://platform.claude.com/docs/pt-BR/build-with-claude/files#file-expiration)).

### Namespace beta do SDK

A partir do 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 e C# SDK 12.44.0, `client.beta.files` não envia mais `files-api-2025-04-14` e retorna os mesmos formatos que `client.files`, com nomes de tipo prefixados com `Beta`. Ele aceita um argumento `betas` para recursos de Files que ainda estão em beta, como a filtragem por `scope_id` sob um cabeçalho beta de [Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/files). Versões anteriores do SDK são tipadas com os formatos beta; se você depende desses tipos, permaneça em uma versão anterior até migrar.

Requisições que carregam `anthropic-beta: managed-agents-2026-04-01` sem `files-api-2025-04-14` recebem os formatos desta página com uma concessão de compatibilidade em `GET /v1/files`: `before_id` e `after_id` ainda são aceitos (não combináveis com `page` ou `ids[]`), e a resposta de listagem inclui `has_more`, `first_id` e `last_id` junto com `next_page`. Versões beta posteriores de Managed Agents recebem o formato simples.

## Tratamento de erros

Erros comuns ao usar a Files API incluem:

* **Arquivo não encontrado (404):** O `file_id` especificado não existe ou você não tem acesso a ele
* **Tipo de arquivo inválido (400):** O tipo de arquivo não corresponde ao tipo de bloco de conteúdo (por exemplo, usar um arquivo de imagem em um bloco de documento)
* **Não baixável (400):** Arquivos que você envia têm `"downloadable": false` e não podem ser baixados. Somente arquivos criados por skills ou pela ferramenta de execução de código podem ser baixados
* **Excede o tamanho da janela de contexto (400):** O arquivo é maior que o tamanho da "context window" (janela de contexto) (por exemplo, usar um arquivo de texto simples de 500 MB em uma requisição `/v1/messages`)
* **Nome de arquivo inválido (400):** O nome do arquivo não atende aos requisitos de comprimento (1 a 255 caracteres) ou contém caracteres proibidos (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/` ou caracteres Unicode 0-31)
* **Arquivo muito grande (413):** O arquivo excede o limite de 500 MB
* **Limite de armazenamento excedido (400):** Sua organização atingiu o limite de armazenamento de 1 TB

```json Output
{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
  },
  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}
```

## Uso e cobrança

As operações da Files API são gratuitas:

* Fazer upload de arquivos
* Baixar arquivos
* Listar arquivos
* Obter metadados de arquivos
* Excluir arquivos

O conteúdo de arquivos usado em requisições de Messages é cobrado como tokens de entrada.

### Limites de taxa

As chamadas de API relacionadas a arquivos são limitadas a aproximadamente 500 requisições por minuto. Para solicitar um "rate limit" (limite de taxa) maior, [entre em contato com vendas](mailto:sales@anthropic.com).

## Próximos passos

<CardGroup cols={3}>
  <Card title="Suporte a PDF" icon="file" href="https://platform.claude.com/docs/pt-BR/build-with-claude/pdf-support">
    Processe PDFs com o Claude. Extraia texto, analise gráficos e compreenda o conteúdo visual dos seus documentos.
  </Card>

  <Card title="Ferramenta de execução de código" icon="terminal" href="https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool">
    Execute código Python e bash em um contêiner isolado para analisar dados, gerar arquivos e iterar em soluções.
  </Card>

  <Card title="Visão" icon="image" href="https://platform.claude.com/docs/pt-BR/build-with-claude/vision">
    Processe e analise entradas visuais e gere texto e código a partir de imagens.
  </Card>
</CardGroup>