---
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: stable
  zdr:
    eligibility: not-eligible
    note: File conservati finché non vengono eliminati esplicitamente o raggiungono la scadenza configurata.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: stable
    Claude Platform on AWS: stable
    Claude Models on Google Cloud (Anthropic managed): stable
    Microsoft Foundry (hosted on Anthropic): stable
---

**Supporto API**: L’utilizzo varia in base al prodotto.

* **Messages API**: Fai riferimento a un file caricato tramite il suo `file_id` in un blocco `document`, `image` o `container_upload`.
* **Managed Agents**: Monta i file nella sandbox della sessione o fai riferimento a un `file_id` in un evento `user.message`.

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 gli attuali modelli Claude. 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#availability-feature-support), 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" title="I file caricati sono accessibili all’intero workspace">
  I file 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 account di servizio, e ogni utente il cui ruolo nell’organizzazione consente l’accesso all’API, può usare il workspace predefinito oltre a qualsiasi workspace a cui lo aggiungi, quindi tieni i file che devono restare separati nel proprio workspace e accedi a essi solo con [chiavi limitate a quel workspace](https://platform.claude.com/docs/it/manage-claude/workspaces#api-keys-and-resource-scoping). Non accettare mai valori `file_id` da utenti finali o da altre fonti non attendibili: un ID file fornito da un utente consentirebbe a un utente della tua applicazione di leggere contenuti caricati da un altro utente. Tratta gli ID file come riferimenti lato server e mantieni nella tua applicazione la mappatura tra i tuoi utenti e i loro file.

  Se stai creando un’applicazione multitenant sulla Files API, crea un [workspace](https://platform.claude.com/docs/it/manage-claude/workspaces) separato per ciascun tenant. Il workspace è il confine di isolamento per i file, quindi un workspace per ciascun tenant garantisce ai dati di quel tenant un isolamento rigido da ogni altro tenant. Ogni organizzazione può avere fino a 100 workspace; contatta il tuo team di riferimento 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: 2026-10-21" \
    -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(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();
  IO.println(fileId);
  ```

  ```php PHP
  $document = fopen('/path/to/document.pdf', 'rb')
      ?: throw new \RuntimeException('Could not open /path/to/document.pdf.');

  $file = $client->files->upload(
      file: FileParam::fromResource($document, 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`](https://platform.claude.com/docs/it/api/files#file_metadata.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).

Il riferimento API descrive ogni campo dell’oggetto file.

(See `file_metadata` on `files` in [the API reference](https://platform.claude.com/docs/it/api/files#file_metadata).)

### 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: 2026-10-21" \
    -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 UserMessageParam
              {
                  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)
      .addUserMessageOfContentBlockParams(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);
  IO.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: Model::CLAUDE_OPUS_5_5,
  );

  echo $response;
  ```

  ```ruby Ruby
  response = client.messages.create(
    model: Anthropic::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 (consulta [Caricare e analizzare i propri file](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)) | Varia                                                | `container_upload`          | Analisi dei dati, visualizzazione            |

#### Blocchi documento

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 immagine

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

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

#### Blocchi di caricamento nel container

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 utilizzando un blocco `container_upload` (consulta [Caricare e analizzare i propri file](https://platform.claude.com/docs/it/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)).

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

<CodeGroup>
  ```bash cURL
  # Codifica il testo del file come stringa JSON, così virgolette e a capo sono sicuri
  TEXT_JSON=$(jq -Rs . document.txt)

  curl https://api.anthropic.com/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -d @- <<EOF
  {
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Here's the document content:"},
          {"type": "text", "text": ${TEXT_JSON}},
          {"type": "text", "text": "Please 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 <<'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:

  {text_content}

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

  ${textContent}

  Please summarize this document.`
          }
        ]
      }
    ]
  });

  const textBlock = response.content.find((block) => 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 UserMessageParam
      {
          Content = $"""
              Here's the document content:

              {textContent}

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

          %s

          Please summarize this document.""".formatted(textContent)
      )
      .build();

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

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

  // Leggi il file di testo
  $textContent = file_get_contents('document.txt')
      ?: throw new \RuntimeException('Could not read document.txt.');

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [
          [
              'role' => 'user',
              'content' => [
                  [
                      'type' => 'text',
                      'text' => <<<TEXT
                          Here's the document content:

                          {$textContent}

                          Please summarize this document.
                          TEXT
                  ]
              ]
          ]
      ],
      model: Model::CLAUDE_OPUS_5_5,
  );

  foreach ($message->content as $block) {
      if ($block instanceof \Anthropic\Messages\TextBlock) {
          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: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: [
          {
            type: "text",
            text: <<~TEXT.chomp
              Here's the document content:

              #{text_content}

              Please summarize this document.
            TEXT
          }
        ]
      }
    ]
  )

  message.content.each do |block|
    puts block.text if block.is_a?(Anthropic::Models::TextBlock)
  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`](https://platform.claude.com/docs/it/api/files/list#list.limit) file (20 per impostazione predefinita e al massimo 1.000), e il cursore [`next_page`](https://platform.claude.com/docs/it/api/files/list#list.response.next_page) della risposta recupera la pagina successiva quando viene ripassato come parametro [`page`](https://platform.claude.com/docs/it/api/files/list#list.page). I file sono ordinati dal più recente. Consulta il [riferimento API Elenca i file](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).

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

  ```bash CLI
  # I comandi list paginano automaticamente, quindi --max-items limita il totale
  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();
      IO.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[]` differisce da un elenco paginato in tre modi:

* Non puoi combinare `ids[]` con `page` o `limit`.
* La risposta è sempre una singola pagina (`next_page` è `null`).
* Se un ID non corrisponde a un file nel tuo workspace, l’API omette quell’ID da `data` senza restituire un errore. Per trovare gli ID omessi dall’API, confronta gli ID restituiti con gli ID richiesti.

#### 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: 2026-10-21"
  ```

  ```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);

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

Elimina 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: 2026-10-21"
  ```

  ```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 ha creato il file. Usa quel `file_id` nella richiesta di download:

<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: 2026-10-21" \
    -o 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(fileId);

  await writeFile("downloaded_file.txt", content.body!);
  ```

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

  IO.copy_stream(file_content, "downloaded_file.txt")
  ```
</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 ciascun file
* **Spazio di archiviazione totale:** 1 TB per ciascuna 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 attive alla Messages API e negli usi degli strumenti associati.
* I file eliminati dagli utenti 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.

### Scadenza dei file

Per fare in modo che un file scada automaticamente, includi un campo del modulo [`expires_in_seconds`](https://platform.claude.com/docs/it/api/files/upload#upload.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`](https://platform.claude.com/docs/it/api/files#file_metadata.expires_at) risultante (RFC 3339) compare in ogni risposta relativa ai file ed è `null` per i file caricati senza scadenza. La scadenza viene impostata una sola volta al momento del 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 non riesce 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 a comparire nelle risposte di elenco durante tale periodo; 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 liberato dalla tua quota di archiviazione; il contenuto sottostante può essere conservato per un periodo limitato successivo per una revisione di sicurezza prima dell’eliminazione definitiva, e i metadati del file restano visibili fino a 30 giorni dopo la scadenza. Per eliminare un file prima della scadenza pianificata, 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 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. Con l’SDK, chiama `client.files` (csharp, go: `client.Files`; java: `client.files()`; php: `$client->files`) invece di `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`); mantenere `client.beta.files` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) funziona solo con le [versioni dell’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` (csharp, go: `client.Beta.Files`; java: `client.beta().files()`; php: `$client->beta->files`) anche quando non passi alcun nome beta.
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

L’SDK offre la Files API in due namespace. Questa pagina usa il namespace stabile, mentre le funzionalità dei file che sono in beta usano il namespace beta.

A partire dalla versione del tuo SDK indicata nella tabella seguente, il namespace beta differisce da quello delle versioni precedenti in due modi:

* Non invia più `files-api-2025-04-14`.
* Restituisce le stesse strutture del namespace stabile, ma con nomi di tipo con prefisso `Beta`.

La tabella riporta anche i nomi dei namespace di ciascun SDK e dove il namespace beta accetta i valori `anthropic-beta`:

| SDK        | Namespace stabile | Namespace beta                                      | Namespace beta modificato in | I valori `anthropic-beta` vanno in |
| ---------- | ----------------- | --------------------------------------------------- | ---------------------------- | ---------------------------------- |
| Python     | `client.files`    | `client.beta.files`                                 | 1.2.0                        | `betas`                            |
| TypeScript | `client.files`    | `client.beta.files`                                 | 0.122.0                      | `betas`                            |
| C#         | `client.Files`    | `client.Beta.Files`                                 | 12.44.0                      | `Betas`                            |
| Go         | `client.Files`    | `client.Beta.Files`                                 | 1.68.0                       | `Betas`                            |
| Java       | `client.files()`  | `client.beta().files()`                             | 2.59.0                       | `.addBeta()`                       |
| PHP        | `$client->files`  | `$client->beta->files` (classi in `Anthropic\Beta`) | 0.45.0                       | `betas`                            |
| Ruby       | `client.files`    | `client.beta.files`                                 | 1.67.0                       | `betas`                            |

Per una funzionalità dei file che è in beta, usa il namespace beta e passa il valore `anthropic-beta` della funzionalità come mostrato nella tabella. Ad esempio, con un header beta di Managed Agents, `scope_id` limita un elenco di file ai file di una sessione. Per usare `scope_id`, consulta [Elenco e download dei file di sessione](https://platform.claude.com/docs/it/managed-agents/files#listing-and-downloading-session-files).

Nelle versioni precedenti a quella del tuo SDK indicata nella tabella, i tipi del namespace beta corrispondono alle strutture restituite da `files-api-2025-04-14`. Se dipendi da tali tipi, resta su una di tali versioni finché non esegui la migrazione da essi.

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, utilizzo di un file immagine in un blocco documento).
* **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, utilizzo di 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 non consentiti (`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/` o i 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>

## Disponibilità

La funzionalità Files API è disponibile su tutti i modelli.

### Supporto API

#### [Messages API](https://platform.claude.com/docs/it/build-with-claude/working-with-messages)

* Disponibilità: Disponibile
* Utilizzo: Fai riferimento a un file caricato tramite il suo `file_id` in un blocco `document`, `image` o `container_upload`.

| Stato       | Piattaforme cloud                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Disponibile | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/it/build-with-claude/claude-in-microsoft-foundry) |

#### [Managed Agents](https://platform.claude.com/docs/it/managed-agents/overview)

* Disponibilità: Disponibile
* Utilizzo: Monta i file caricati nella sandbox della sessione come risorse di sessione (in sola lettura, in `/mnt/session/uploads`) o fai riferimento a un `file_id` in un blocco `image` o `document` di un evento `user.message`. I file che l’agente scrive in `/mnt/session/outputs/` possono essere scaricati con la Files API.

| Stato       | Piattaforme cloud               |
| ----------- | ------------------------------- |
| Disponibile | Tutte le piattaforme supportate |

### Gestione dei dati

[Panoramica sulla gestione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention#feature-eligibility)

| Elemento | Conservazione zero dei dati                                                                                                                                                                    | HIPAA      |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| Stato    | Non idoneo                                                                                                                                                                                     | Non idoneo |
| Dettagli | File conservati finché non vengono eliminati esplicitamente o raggiungono la scadenza configurata. [Scopri di più](https://platform.claude.com/docs/it/build-with-claude/files#data-retention) | —          |

Endpoint applicabili:

* `/v1/files`
