---
title: Files API
url: https://platform.claude.com/docs/it/build-with-claude/files
description: Carica i file una sola volta, fai riferimento a essi tramite file_id nelle richieste Messages e scarica gli output creati dalle skill o dallo strumento di esecuzione del codice.
featureMetadata:
  status: ga
  zdr: not-eligible
  supportedPlatforms:
    Claude API: ga
    Claude Platform on AWS: ga
    Microsoft Foundry:
      availability: ga
      note: Su [Microsoft Foundry](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry), la Files API richiede un [deployment Hosted on Anthropic](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
---

La Files API ti consente di caricare e gestire file da usare con la Claude API senza dover ricaricare il contenuto a ogni richiesta. Questo è particolarmente utile quando usi lo [strumento di esecuzione del codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool) per fornire input (ad esempio, dataset e documenti) e poi scaricare gli output (ad esempio, grafici). Puoi [esplorare direttamente il riferimento API](https://platform.claude.com/docs/it/api/files/upload), oltre a questa guida.

## Supporto dei tipi di file

Il riferimento a un `file_id` in una richiesta Messages è supportato su tutti i modelli che supportano il tipo di file in questione. Le [immagini](https://platform.claude.com/docs/it/build-with-claude/vision) sono supportate su tutti i modelli Claude attuali. Per i [PDF](https://platform.claude.com/docs/it/build-with-claude/pdf-support) e gli [altri tipi di file con lo strumento di esecuzione del codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#compatibility), consulta le pagine collegate per il supporto dei modelli.

## Come funziona la Files API

La Files API offre un approccio "crea una volta, usa molte volte" per lavorare con i file:

* **Carica file** nello storage sicuro di Anthropic e ricevi un `file_id` univoco
* **Scarica file** creati dalle skill o dallo strumento di esecuzione del codice
* **Fai riferimento ai file** nelle richieste [Messages](https://platform.claude.com/docs/it/api/messages/create) usando il `file_id` invece di ricaricare il contenuto
* **Gestisci i tuoi file** con operazioni di elenco, recupero ed eliminazione

<Warning id="workspace-scoped-access">
  **I file caricati sono accessibili all'intero workspace, non sono limitati a un utente finale, a una conversazione o a una sessione.** Qualsiasi chiave API con accesso a un workspace può accedere a qualsiasi file caricato in quel workspace. Ogni service account, e ogni utente il cui ruolo nell'organizzazione consente l'accesso API, può usare il Default Workspace oltre a qualsiasi workspace a cui lo aggiungi, quindi mantieni i file che devono restare separati in un proprio [workspace](https://platform.claude.com/docs/it/manage-claude/workspaces#api-keys-and-resource-scoping) e accedi a essi solo con chiavi limitate a quel workspace. Non accettare mai valori `file_id` da utenti finali o da altre fonti non attendibili: un ID file fornito dall'utente permetterebbe a un utente della tua applicazione di leggere contenuti caricati da un altro utente. Tratta gli ID file come riferimenti lato server e mantieni la mappatura tra i tuoi utenti e i loro file nella tua applicazione.

  Se stai costruendo un'applicazione multi-tenant sulla Files API, crea un [workspace](https://platform.claude.com/docs/it/manage-claude/workspaces) separato per ogni tenant. Il workspace è il confine di isolamento per i file, quindi un workspace per tenant garantisce ai dati di ciascun tenant un isolamento rigido da ogni altro tenant. Ogni organizzazione può avere fino a 100 workspace; contatta il tuo account team se ne hai bisogno di più.
</Warning>

## Come usare la Files API

### Caricare un file

Carica un file a cui fare riferimento nelle future chiamate 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 risposta al caricamento di un file include:

```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` per i file che carichi. Solo i file creati dalle [skill](https://platform.claude.com/docs/it/build-with-claude/skills-guide) o dallo [strumento di esecuzione del codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool) possono essere scaricati. Consulta [Scaricare un file](https://platform.claude.com/docs/it/build-with-claude/files#downloading-a-file).

### Usare un file nei messaggi

Una volta caricato, fai riferimento al file passando l'`id` della risposta di caricamento come `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>

### Tipi di file e blocchi di contenuto

La Files API supporta diversi tipi di file che corrispondono a diversi tipi di blocchi di contenuto:

| Tipo di file                                                                                                                          | Tipo MIME                                            | Tipo di blocco di contenuto | Caso d'uso                                    |
| ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | --------------------------- | --------------------------------------------- |
| PDF                                                                                                                                   | `application/pdf`                                    | `document`                  | Analisi del testo, elaborazione di documenti  |
| Testo semplice                                                                                                                        | `text/plain`                                         | `document`                  | Analisi del testo, elaborazione               |
| Immagini                                                                                                                              | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image`                     | Analisi di immagini, attività visive          |
| [Dataset, altri](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) | Variabile                                            | `container_upload`          | Analisi di dati, creazione di visualizzazioni |

#### Blocchi document

Per PDF e file di testo, usa il blocco di contenuto `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
}
```

#### Blocchi image

Per le immagini, usa il blocco di contenuto `image`:

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

#### Blocchi container upload

Per inviare un file allo [strumento di esecuzione del codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files), usa il blocco di contenuto `container_upload`:

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

### Lavorare con altri formati di file

Per i tipi di file che il blocco `document` non supporta (ad esempio, .docx e .xlsx), converti i file in testo semplice e includi il contenuto direttamente nel tuo messaggio. I file che sono già in testo semplice, come i file .csv e .md, possono essere letti in questo modo oppure caricati tramite la Files API con un tipo di contenuto `text/plain` esplicito. Per analizzare i dataset invece di leggerli come testo, caricali per lo [strumento di esecuzione del codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) usando un blocco `container_upload`.

Gli esempi seguenti leggono un file di testo e ne inviano il contenuto come testo semplice:

<CodeGroup>
  ```bash cURL
  # Leggi il file di testo
  # Nota: per i file con caratteri speciali, valuta la codifica 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
  # Il riferimento "@./path" inserisce il contenuto del file direttamente nel 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()

  # Leggi il file di testo
  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();

  // Leggi il file di testo
  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();

  // Leggi il file di testo
  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()

  // Leggi il file di testo
  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();

  // Leggi il file di testo
  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();

  // Leggi il file di testo
  $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

  # Leggi il file di testo
  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>
  Per i file .docx contenenti immagini, convertili prima in formato PDF, poi usa il [supporto PDF](https://platform.claude.com/docs/it/build-with-claude/pdf-support) per sfruttare l'analisi delle immagini integrata. Questo consente di usare le citazioni dal documento PDF.
</Note>

### Gestire i file

#### Elencare i file

Recupera un elenco dei file che hai caricato. L'endpoint è paginato: ogni richiesta restituisce fino a `limit` file (20 per impostazione predefinita e al massimo 1.000), e il cursore `next_page` della risposta recupera la pagina successiva quando viene ripassato come parametro `page`. I file sono ordinati dal più recente. Consulta il [riferimento API List Files](https://platform.claude.com/docs/it/api/files/list). L'SDK restituisce la prima pagina e fornisce helper di [paginazione automatica](https://platform.claude.com/docs/it/api/overview#pagination). L'esempio CLI limita il totale 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>

Per verificare un insieme noto di file in una singola richiesta invece di paginare, passa fino a 100 ID file come parametri di query `ids[]`. Una richiesta `ids[]` restituisce sempre una singola pagina (`next_page` è `null`), e qualsiasi ID che non corrisponde a un file nel tuo workspace viene omesso silenziosamente da `data`; confronta gli ID restituiti con gli ID richiesti per rilevare quelli mancanti. `ids[]` non può essere combinato con `page` o `limit`.

#### Ottenere i metadati di un file

Recupera le informazioni su un file specifico:

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

#### Eliminare un file

Rimuovi un file dal tuo 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>

### Scaricare un file

Scarica i file creati dalle [skill](https://platform.claude.com/docs/it/build-with-claude/skills-guide) o dallo [strumento di esecuzione del codice](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool). I file che carichi non possono essere scaricati. Il `file_id` di un file generato appare nel [blocco di contenuto `bash_code_execution_tool_result`](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files) della risposta Messages che lo ha creato:

<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 file è scaricabile solo quando i suoi metadati mostrano `"downloadable": true`, come avviene per i file creati dalle skill o dallo strumento di esecuzione del codice. Scaricare un file che hai caricato restituisce un errore 400.
</Note>

Sulla Claude API, i file di immagine, video e audio supportati che Claude produce con lo strumento di esecuzione del codice, inclusi i file creati dalle skill, includono Content Credentials C2PA firmate quando li scarichi. Consulta [Content Credentials sui file generati](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#content-credentials-on-generated-files) per sapere cosa contiene la credenziale e come verificarla.

## Archiviazione dei file e limiti

### Limiti di archiviazione

* **Dimensione massima del file:** 500 MB per file
* **Archiviazione totale:** 1 TB per organizzazione

### Ciclo di vita dei file

* I file sono limitati al workspace in cui sono stati caricati. Qualsiasi richiesta nello stesso workspace può farvi riferimento; non accettare mai ID file da fonti non attendibili (consulta l'[avviso sull'accesso al workspace](https://platform.claude.com/docs/it/build-with-claude/files#workspace-scoped-access))
* I file non possono essere modificati o rinominati dopo il caricamento. Per cambiare il contenuto di un file, carica un nuovo file ed elimina quello vecchio
* I file persistono finché non li elimini con l'endpoint `DELETE /v1/files/{file_id}` o finché non raggiungono il loro `expires_at`
* I file eliminati non possono essere recuperati
* I file diventano inaccessibili tramite l'API poco dopo l'eliminazione, ma possono persistere nelle chiamate Messages API attive e negli usi degli strumenti associati
* I file che gli utenti eliminano verranno eliminati in conformità con la [politica di conservazione dei dati](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data) di Anthropic. Per l'idoneità ZDR di tutte le funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention)

### Scadenza dei file

Per far scadere automaticamente un file, includi un campo form `expires_in_seconds` quando lo carichi. Il valore è un numero intero di secondi compreso tra 3.600 (1 ora) e 7.776.000 (90 giorni). Il timestamp `expires_at` risultante (RFC 3339) appare in ogni risposta relativa al file ed è `null` per i file caricati senza scadenza. La scadenza viene impostata una sola volta al caricamento e non può essere modificata.

Quando un file raggiunge il suo `expires_at`:

* Il download del suo contenuto (`GET /v1/files/{file_id}/content`) restituisce un errore 404
* Una richiesta Messages che fa riferimento al file fallisce prima dell'inferenza
* I suoi metadati (`GET /v1/files/{file_id}`) restano leggibili per un massimo di 30 giorni, con `expires_at` nel passato
* Continua ad apparire nelle risposte di elenco durante quella finestra; confronta `expires_at` con l'ora corrente per filtrare i file scaduti

Eliminare un file scaduto con `DELETE /v1/files/{file_id}` rimuove immediatamente i suoi metadati invece di attendere che trascorra la finestra di 30 giorni.

<Note>
  La scadenza è una funzionalità del ciclo di vita, non un controllo di eliminazione garantita. Dopo `expires_at`, il contenuto del file non è più recuperabile tramite l'API e viene rilasciato dalla tua quota di archiviazione; il contenuto sottostante può essere conservato per un periodo limitato successivo per la revisione di sicurezza prima dell'eliminazione permanente, e i metadati del file restano visibili per un massimo di 30 giorni dopo la scadenza. Per rimuovere un file prima della scadenza programmata, usa `DELETE /v1/files/{file_id}`.
</Note>

### Registrazione di audit

Se la tua organizzazione ha la [Compliance API](https://platform.claude.com/docs/it/manage-claude/compliance-api) abilitata, il suo [Activity Feed](https://platform.claude.com/docs/it/manage-claude/compliance-activity-feed) registra le operazioni della Files API effettuate con una chiave API Claude o dalla Claude Console: ogni caricamento (`POST /v1/files`), download di contenuto (`GET /v1/files/{file_id}/content`) ed eliminazione (`DELETE /v1/files/{file_id}`) appare come attività `platform_file_uploaded`, `platform_file_content_downloaded` o `platform_file_deleted`. L'elenco dei file e il recupero dei metadati dei file non vengono registrati. Le operazioni che avvengono mentre la Compliance API è disattivata non vengono registrate e non possono essere recuperate in seguito, quindi [configura la Compliance API](https://platform.claude.com/docs/it/manage-claude/compliance-api-access) prima di fare affidamento su questa traccia di audit. Su [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws#monitoring-and-logging), esegui invece l'audit delle operazioni sui file con gli eventi dati di AWS CloudTrail.

## Migrare da `files-api-2025-04-14`

La Files API è uscita dalla beta e non richiede alcun header beta. La migrazione da `files-api-2025-04-14` è facoltativa: le richieste che lo inviano ancora continuano a funzionare e continuano a restituire le forme di risposta beta, quindi un'integrazione esistente continua a funzionare finché non la modifichi. Rimuovere l'header fa passare quelle richieste alle forme documentate in questa pagina:

|                                              | Con `files-api-2025-04-14`              | Senza l'header                                                                           |
| -------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- |
| Risposta di elenco                           | `{ data, has_more, first_id, last_id }` | `{ data, next_page }`; ripassa `next_page` come parametro di query `page`                |
| Cursori di elenco                            | `before_id`, `after_id`                 | `page`, oppure fino a 100 `ids[]` (`before_id` e `after_id` restituiscono un errore 400) |
| `expires_at` sugli oggetti file              | Non restituito                          | Sempre presente; `null` quando il file non ha scadenza                                   |
| `Content-Type` sulla parte del file caricato | Obbligatorio                            | Facoltativo; il tipo viene rilevato quando omesso                                        |

Per migrare:

1. **Rimuovi l'header beta.** Elimina `anthropic-beta: files-api-2025-04-14` dalle tue richieste. Negli SDK, chiama `client.files` invece di `client.beta.files`; mantenere `client.beta.files` funziona solo sulle [versioni degli SDK che non inviano più l'header](https://platform.claude.com/docs/it/build-with-claude/files#sdk-beta-namespace). Le versioni precedenti lo inviano da `client.beta.files` anche senza argomento `betas`.
2. **Aggiorna la paginazione.** Sostituisci i cicli `after_id`/`before_id` con il cursore `page`/`next_page`, oppure usa gli helper di auto-paginazione degli SDK mostrati in [Gestire i file](https://platform.claude.com/docs/it/build-with-claude/files#managing-files).
3. **Leggi `expires_at`.** Il campo appare solo senza l'header; `null` significa che il file non ha scadenza (consulta [Scadenza dei file](https://platform.claude.com/docs/it/build-with-claude/files#file-expiration)).

### Namespace beta degli SDK

A partire da 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` non invia più `files-api-2025-04-14` e restituisce le stesse forme di `client.files`, con nomi di tipo con prefisso `Beta`. Accetta un argomento `betas` per le funzionalità Files ancora in beta, come il filtro `scope_id` sotto un header beta [Managed Agents](https://platform.claude.com/docs/it/managed-agents/files). Le versioni precedenti degli SDK sono tipizzate sulle forme beta; se dipendi da quei tipi, resta su una versione precedente finché non migri.

Le richieste che contengono `anthropic-beta: managed-agents-2026-04-01` senza `files-api-2025-04-14` ricevono le forme di questa pagina con una concessione di compatibilità su `GET /v1/files`: `before_id` e `after_id` sono ancora accettati (non combinabili con `page` o `ids[]`), e la risposta di elenco include `has_more`, `first_id` e `last_id` insieme a `next_page`. Le versioni beta successive di Managed Agents ricevono la forma semplice.

## Gestione degli errori

Gli errori comuni nell'uso della Files API includono:

* **File non trovato (404):** Il `file_id` specificato non esiste o non hai accesso a esso
* **Tipo di file non valido (400):** Il tipo di file non corrisponde al tipo di blocco di contenuto (ad esempio, usare un file immagine in un blocco document)
* **Non scaricabile (400):** I file che carichi hanno `"downloadable": false` e non possono essere scaricati. Solo i file creati dalle skill o dallo strumento di esecuzione del codice possono essere scaricati
* **Supera la dimensione della finestra di contesto (400):** Il file è più grande della dimensione della "context window" (finestra di contesto) (ad esempio, usare un file di testo semplice da 500 MB in una richiesta `/v1/messages`)
* **Nome file non valido (400):** Il nome del file non soddisfa i requisiti di lunghezza (1-255 caratteri) o contiene caratteri vietati (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/` o caratteri Unicode 0-31)
* **File troppo grande (413):** Il file supera il limite di 500 MB
* **Limite di archiviazione superato (400):** La tua organizzazione ha raggiunto il limite di archiviazione di 1 TB

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

## Utilizzo e fatturazione

Le operazioni della Files API sono gratuite:

* Caricamento di file
* Download di file
* Elenco dei file
* Recupero dei metadati dei file
* Eliminazione di file

Il contenuto dei file usato nelle richieste Messages viene tariffato come token di input.

### Limiti di velocità

Le chiamate API relative ai file sono soggette a un "rate limit" (limite di velocità) di circa 500 richieste al minuto. Per richiedere un limite più alto, [contatta il team commerciale](mailto:sales@anthropic.com).

## Passaggi successivi

<CardGroup cols={3}>
  <Card title="Supporto PDF" icon="file" href="https://platform.claude.com/docs/it/build-with-claude/pdf-support">
    Elabora i PDF con Claude. Estrai testo, analizza grafici e comprendi il contenuto visivo dei tuoi documenti.
  </Card>

  <Card title="Strumento di esecuzione del codice" icon="terminal" href="https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool">
    Esegui codice Python e bash in un container sandbox per analizzare dati, generare file e iterare sulle soluzioni.
  </Card>

  <Card title="Visione" icon="image" href="https://platform.claude.com/docs/it/build-with-claude/vision">
    Elabora e analizza input visivi e genera testo e codice a partire dalle immagini.
  </Card>
</CardGroup>