---
title: Files API
url: https://platform.claude.com/docs/ko/build-with-claude/files
description: 파일을 한 번 업로드한 뒤 Messages 요청에서 file_id로 참조하고, skills 또는 코드 실행 도구가 생성한 출력을 다운로드합니다.
featureMetadata:
  status: ga
  zdr: not-eligible
  supportedPlatforms:
    Claude API: ga
    Claude Platform on AWS: ga
    Microsoft Foundry:
      availability: ga
      note: "[Microsoft Foundry](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry)에서 Files API를 사용하려면 [Hosted on Anthropic 배포](https://platform.claude.com/docs/ko/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure)가 필요합니다."
---

Files API를 사용하면 요청마다 콘텐츠를 다시 업로드하지 않고도 Claude API와 함께 사용할 파일을 업로드하고 관리할 수 있습니다. 이는 [코드 실행 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool)를 사용하여 입력(예: 데이터셋 및 문서)을 제공한 다음 출력(예: 차트)을 다운로드할 때 특히 유용합니다. 이 가이드 외에도 [API 레퍼런스를 직접 살펴볼](https://platform.claude.com/docs/ko/api/files/upload) 수 있습니다.

## 파일 유형 지원

Messages 요청에서 `file_id`를 참조하는 것은 해당 파일 유형을 지원하는 모든 모델에서 지원됩니다. [이미지](https://platform.claude.com/docs/ko/build-with-claude/vision)는 현재 모든 Claude 모델에서 지원됩니다. [PDF](https://platform.claude.com/docs/ko/build-with-claude/pdf-support) 및 [코드 실행 도구와 함께 사용하는 기타 파일 유형](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool#compatibility)의 경우, 모델 지원에 대해서는 링크된 페이지를 참조하세요.

## Files API 작동 방식

Files API는 파일 작업을 위한 한 번 생성, 여러 번 사용 방식을 제공합니다:

* Anthropic의 보안 저장소에 **파일을 업로드**하고 고유한 `file_id`를 받습니다
* 스킬이나 코드 실행 도구가 생성한 **파일을 다운로드**합니다
* 콘텐츠를 다시 업로드하는 대신 `file_id`를 사용하여 [Messages](https://platform.claude.com/docs/ko/api/messages/create) 요청에서 **파일을 참조**합니다
* 목록 조회, 검색, 삭제 작업으로 **파일을 관리**합니다

<Warning id="workspace-scoped-access">
  **업로드된 파일은 최종 사용자, 대화 또는 세션으로 범위가 제한되지 않고 전체 워크스페이스에서 접근할 수 있습니다.** 워크스페이스에 접근할 수 있는 모든 API 키는 해당 워크스페이스에 업로드된 모든 파일에 접근할 수 있습니다. 모든 서비스 계정과 조직 역할이 API 접근을 허용하는 모든 사용자는 추가한 워크스페이스 외에도 Default Workspace를 사용할 수 있으므로, 분리되어야 하는 파일은 자체 [워크스페이스](https://platform.claude.com/docs/ko/manage-claude/workspaces#api-keys-and-resource-scoping)에 보관하고 해당 워크스페이스로 범위가 제한된 키로만 접근하세요. 최종 사용자나 기타 신뢰할 수 없는 소스로부터 `file_id` 값을 절대 받지 마세요. 사용자가 제공한 파일 ID는 애플리케이션의 한 사용자가 다른 사용자가 업로드한 콘텐츠를 읽을 수 있게 합니다. 파일 ID를 서버 측 참조로 취급하고, 사용자와 해당 파일 간의 매핑을 애플리케이션에 유지하세요.

  Files API에서 멀티 테넌트 애플리케이션을 구축하는 경우, 각 테넌트마다 별도의 [워크스페이스](https://platform.claude.com/docs/ko/manage-claude/workspaces)를 생성하세요. 워크스페이스는 파일의 격리 경계이므로, 테넌트당 하나의 워크스페이스를 사용하면 각 테넌트의 데이터가 다른 모든 테넌트로부터 강력하게 격리됩니다. 각 조직은 최대 100개의 워크스페이스를 가질 수 있습니다. 더 필요한 경우 계정 팀에 문의하세요.
</Warning>

## Files API 사용 방법

### 파일 업로드

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

파일 업로드에 대한 응답에는 다음이 포함됩니다:

```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`입니다. [스킬](https://platform.claude.com/docs/ko/build-with-claude/skills-guide)이나 [코드 실행 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool)가 생성한 파일만 다운로드할 수 있습니다. [파일 다운로드](https://platform.claude.com/docs/ko/build-with-claude/files#downloading-a-file)를 참조하세요.

### 메시지에서 파일 사용

업로드한 후에는 업로드 응답의 `id`를 `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>

### 파일 유형 및 콘텐츠 블록

Files API는 서로 다른 콘텐츠 블록 유형에 해당하는 다양한 파일 유형을 지원합니다:

| 파일 유형                                                                                                                           | MIME 유형                                              | 콘텐츠 블록 유형          | 사용 사례          |
| ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------ | -------------- |
| PDF                                                                                                                             | `application/pdf`                                    | `document`         | 텍스트 분석, 문서 처리  |
| 일반 텍스트                                                                                                                          | `text/plain`                                         | `document`         | 텍스트 분석, 처리     |
| 이미지                                                                                                                             | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | `image`            | 이미지 분석, 시각적 작업 |
| [데이터셋, 기타](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files) | 다양함                                                  | `container_upload` | 데이터 분석, 시각화 생성 |

#### 문서 블록

PDF 및 텍스트 파일의 경우 `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
}
```

#### 이미지 블록

이미지의 경우 `image` 콘텐츠 블록을 사용합니다:

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

#### 컨테이너 업로드 블록

[코드 실행 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)에 파일을 보내려면 `container_upload` 콘텐츠 블록을 사용합니다:

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

### 기타 파일 형식 작업

`document` 블록이 지원하지 않는 파일 유형(예: .docx 및 .xlsx)의 경우, 파일을 일반 텍스트로 변환하고 콘텐츠를 메시지에 직접 포함하세요. .csv 및 .md 파일과 같이 이미 일반 텍스트인 파일은 이 방식으로 읽거나 명시적인 `text/plain` 콘텐츠 유형으로 Files API를 통해 업로드할 수 있습니다. 데이터셋을 텍스트로 읽는 대신 분석하려면, `container_upload` 블록을 사용하여 [코드 실행 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool#upload-and-analyze-your-own-files)용으로 업로드하세요.

다음 예제는 텍스트 파일을 읽고 그 내용을 일반 텍스트로 전송합니다:

<CodeGroup>
  ```bash cURL
  # 텍스트 파일을 읽습니다
  # 참고: 특수 문자가 포함된 파일은 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
  # "@./path" 참조는 파일 내용을 해당 필드에 직접 인라인으로 삽입합니다.
  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()

  # 텍스트 파일을 읽습니다
  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();

  // 텍스트 파일을 읽습니다
  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();

  // 텍스트 파일을 읽습니다
  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()

  // 텍스트 파일을 읽습니다
  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();

  // 텍스트 파일을 읽습니다
  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();

  // 텍스트 파일을 읽습니다
  $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

  # 텍스트 파일을 읽습니다
  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>
  이미지가 포함된 .docx 파일의 경우, 먼저 PDF 형식으로 변환한 다음 [PDF 지원](https://platform.claude.com/docs/ko/build-with-claude/pdf-support)을 사용하여 내장된 이미지 파싱을 활용하세요. 이를 통해 PDF 문서의 인용을 사용할 수 있습니다.
</Note>

### 파일 관리

#### 파일 목록 조회

업로드한 파일 목록을 조회합니다. 이 엔드포인트는 "pagination"(페이지네이션)을 사용합니다. 각 요청은 최대 `limit`개의 파일(기본값 20개, 최대 1,000개)을 반환하며, 응답의 `next_page` 커서를 `page` 매개변수로 다시 전달하면 다음 페이지를 가져옵니다. 파일은 최신순으로 정렬됩니다. [List Files API 레퍼런스](https://platform.claude.com/docs/ko/api/files/list)를 참조하세요. SDK는 첫 페이지를 반환하며 [자동 페이지네이션](https://platform.claude.com/docs/ko/api/overview#pagination) 헬퍼를 제공합니다. CLI 예제는 `--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>

페이징 대신 알려진 파일 집합을 한 번의 요청으로 확인하려면, 최대 100개의 파일 ID를 `ids[]` 쿼리 매개변수로 전달하세요. `ids[]` 요청은 항상 단일 페이지를 반환하며(`next_page`는 `null`), 워크스페이스의 파일로 확인되지 않는 ID는 `data`에서 조용히 생략됩니다. 누락을 감지하려면 반환된 ID를 요청한 ID와 비교하세요. `ids[]`는 `page` 또는 `limit`와 결합할 수 없습니다.

#### 파일 메타데이터 가져오기

특정 파일에 대한 정보를 검색합니다:

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

#### 파일 삭제

워크스페이스에서 파일을 제거합니다:

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

### 파일 다운로드

[스킬](https://platform.claude.com/docs/ko/build-with-claude/skills-guide)이나 [코드 실행 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool)가 생성한 파일을 다운로드합니다. 업로드한 파일은 다운로드할 수 없습니다. 생성된 파일의 `file_id`는 해당 파일을 생성한 Messages 응답의 [`bash_code_execution_tool_result` 콘텐츠 블록](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files)에 나타납니다:

<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>
  파일은 메타데이터에 `"downloadable": true`가 표시될 때만 다운로드할 수 있으며, 이는 스킬이나 코드 실행 도구가 생성한 파일의 경우에 해당합니다. 업로드한 파일을 다운로드하면 400 오류가 반환됩니다.
</Note>

Claude API에서는 스킬이 생성한 파일을 포함하여 Claude가 코드 실행 도구로 생성한 지원되는 이미지, 비디오 및 오디오 파일을 다운로드할 때 서명된 C2PA Content Credentials가 포함됩니다. 자격 증명에 포함되는 내용과 검증 방법은 [생성된 파일의 Content Credentials](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool#content-credentials-on-generated-files)를 참조하세요.

## 파일 저장 및 제한

### 저장 제한

* **최대 파일 크기:** 파일당 500 MB
* **총 저장 용량:** 조직당 1 TB

### 파일 수명 주기

* 파일은 업로드된 워크스페이스로 범위가 제한됩니다. 동일한 워크스페이스의 모든 요청이 이를 참조할 수 있습니다. 신뢰할 수 없는 소스로부터 파일 ID를 절대 받지 마세요([워크스페이스 접근 경고](https://platform.claude.com/docs/ko/build-with-claude/files#workspace-scoped-access) 참조)
* 파일은 업로드 후 수정하거나 이름을 변경할 수 없습니다. 파일의 콘텐츠를 변경하려면 새 파일을 업로드하고 이전 파일을 삭제하세요
* 파일은 `DELETE /v1/files/{file_id}` 엔드포인트로 삭제하거나 `expires_at`에 도달할 때까지 유지됩니다
* 삭제된 파일은 복구할 수 없습니다
* 파일은 삭제 직후 API를 통해 접근할 수 없게 되지만, 활성 Messages API 호출 및 관련 도구 사용에서는 유지될 수 있습니다
* 사용자가 삭제한 파일은 Anthropic의 [데이터 보존 정책](https://privacy.claude.com/en/articles/7996866-how-long-do-you-store-my-organization-s-data)에 따라 삭제됩니다. 모든 기능에 대한 ZDR 적격성은 [API 및 데이터 보존](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention)을 참조하세요

### 파일 만료

파일이 자동으로 만료되도록 하려면, 업로드할 때 `expires_in_seconds` 폼 필드를 포함하세요. 값은 3,600(1시간)에서 7,776,000(90일) 사이의 정수 초 단위입니다. 결과로 생성되는 `expires_at` 타임스탬프(RFC 3339)는 모든 파일 응답에 나타나며, 만료 없이 업로드된 파일의 경우 `null`입니다. 만료는 업로드 시 한 번 설정되며 변경할 수 없습니다.

파일이 `expires_at`에 도달하면:

* 콘텐츠 다운로드(`GET /v1/files/{file_id}/content`)는 404 오류를 반환합니다
* 해당 파일을 참조하는 Messages 요청은 추론 전에 실패합니다
* 메타데이터(`GET /v1/files/{file_id}`)는 `expires_at`이 과거인 상태로 최대 30일 동안 읽을 수 있습니다
* 해당 기간 동안 목록 응답에 계속 나타납니다. 만료된 파일을 필터링하려면 `expires_at`을 현재 시간과 비교하세요

`DELETE /v1/files/{file_id}`로 만료된 파일을 삭제하면 30일 기간이 경과할 때까지 기다리지 않고 메타데이터가 즉시 제거됩니다.

<Note>
  만료는 수명 주기 기능이며 보장된 삭제 제어가 아닙니다. `expires_at` 이후에는 파일 콘텐츠를 API를 통해 더 이상 검색할 수 없으며 저장 할당량에서 해제됩니다. 기본 콘텐츠는 영구 삭제 전 안전 검토를 위해 그 이후 제한된 기간 동안 보존될 수 있으며, 파일 메타데이터는 만료 후 최대 30일 동안 계속 표시됩니다. 예정된 만료 전에 파일을 제거하려면 `DELETE /v1/files/{file_id}`를 사용하세요.
</Note>

### 감사 로깅

조직에 [Compliance API](https://platform.claude.com/docs/ko/manage-claude/compliance-api)가 활성화되어 있는 경우, 해당 [Activity Feed](https://platform.claude.com/docs/ko/manage-claude/compliance-activity-feed)는 Claude API 키로 또는 Claude Console에서 수행된 Files API 작업을 기록합니다. 각 업로드(`POST /v1/files`), 콘텐츠 다운로드(`GET /v1/files/{file_id}/content`), 삭제(`DELETE /v1/files/{file_id}`)는 각각 `platform_file_uploaded`, `platform_file_content_downloaded`, `platform_file_deleted` 활동으로 나타납니다. 파일 목록 조회 및 파일 메타데이터 검색은 기록되지 않습니다. Compliance API가 꺼져 있는 동안 발생하는 작업은 기록되지 않으며 나중에 복구할 수 없으므로, 이 감사 추적에 의존하기 전에 [Compliance API를 설정](https://platform.claude.com/docs/ko/manage-claude/compliance-api-access)하세요. [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#monitoring-and-logging)에서는 대신 AWS CloudTrail 데이터 이벤트로 파일 작업을 감사하세요.

## `files-api-2025-04-14`에서 마이그레이션

Files API는 베타에서 벗어났으며 베타 헤더가 필요하지 않습니다. `files-api-2025-04-14`에서 마이그레이션하는 것은 선택 사항입니다. 여전히 이를 전송하는 요청은 계속 작동하고 베타 응답 형태를 계속 반환하므로, 기존 통합은 변경할 때까지 계속 작동합니다. 헤더를 제거하면 해당 요청이 이 페이지에 문서화된 형태로 전환됩니다:

|                            | `files-api-2025-04-14` 사용 시             | 헤더 없이                                                            |
| -------------------------- | --------------------------------------- | ---------------------------------------------------------------- |
| 목록 응답                      | `{ data, has_more, first_id, last_id }` | `{ data, next_page }`; `next_page`를 `page` 쿼리 매개변수로 다시 전달        |
| 목록 커서                      | `before_id`, `after_id`                 | `page`, 또는 최대 100개의 `ids[]`(`before_id` 및 `after_id`는 400 오류 반환) |
| 파일 객체의 `expires_at`        | 반환되지 않음                                 | 항상 존재; 파일에 만료가 없으면 `null`                                        |
| 업로드된 파일 부분의 `Content-Type` | 필수                                      | 선택 사항; 생략 시 유형이 감지됨                                              |

마이그레이션하려면:

1. **베타 헤더를 제거하세요.** 요청에서 `anthropic-beta: files-api-2025-04-14`를 삭제하세요. SDK에서는 `client.beta.files` 대신 `client.files`를 호출하세요. `client.beta.files`를 유지하는 것은 [더 이상 헤더를 전송하지 않는 SDK 릴리스](https://platform.claude.com/docs/ko/build-with-claude/files#sdk-beta-namespace)에서만 작동합니다. 이전 릴리스는 `betas` 인수가 없어도 `client.beta.files`에서 이를 전송합니다.
2. **페이지네이션을 업데이트하세요.** `after_id`/`before_id` 루프를 `page`/`next_page` 커서로 교체하거나, [파일 관리](https://platform.claude.com/docs/ko/build-with-claude/files#managing-files)에 표시된 SDK 자동 페이지네이션 헬퍼를 사용하세요.
3. **`expires_at`을 읽으세요.** 이 필드는 헤더 없이만 나타납니다. `null`은 파일에 만료가 없음을 의미합니다([파일 만료](https://platform.claude.com/docs/ko/build-with-claude/files#file-expiration) 참조).

### SDK 베타 네임스페이스

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, C# SDK 12.44.0부터 `client.beta.files`는 더 이상 `files-api-2025-04-14`를 전송하지 않으며 `Beta` 접두사가 붙은 유형 이름으로 `client.files`와 동일한 형태를 반환합니다. 이는 [Managed Agents](https://platform.claude.com/docs/ko/managed-agents/files) 베타 헤더 하의 `scope_id` 필터링과 같이 여전히 베타 상태인 Files 기능에 대해 `betas` 인수를 허용합니다. 이전 SDK 릴리스는 베타 형태로 타입이 지정되어 있습니다. 해당 유형에 의존하는 경우, 마이그레이션할 때까지 이전 릴리스를 유지하세요.

`files-api-2025-04-14` 없이 `anthropic-beta: managed-agents-2026-04-01`을 전달하는 요청은 `GET /v1/files`에 대한 하나의 호환성 편의 기능과 함께 이 페이지의 형태를 받습니다: `before_id` 및 `after_id`는 여전히 허용되며(`page` 또는 `ids[]`와 결합 불가), 목록 응답에는 `next_page`와 함께 `has_more`, `first_id`, `last_id`가 포함됩니다. 이후 Managed Agents 베타 버전은 일반 형태를 받습니다.

## 오류 처리

Files API 사용 시 일반적인 오류는 다음과 같습니다:

* **파일을 찾을 수 없음(404):** 지정된 `file_id`가 존재하지 않거나 접근 권한이 없습니다
* **잘못된 파일 유형(400):** 파일 유형이 콘텐츠 블록 유형과 일치하지 않습니다(예: 문서 블록에서 이미지 파일 사용)
* **다운로드 불가(400):** 업로드한 파일은 `"downloadable": false`이며 다운로드할 수 없습니다. 스킬이나 코드 실행 도구가 생성한 파일만 다운로드할 수 있습니다
* **컨텍스트 윈도우 크기 초과(400):** 파일이 컨텍스트 윈도우 크기보다 큽니다(예: `/v1/messages` 요청에서 500 MB 일반 텍스트 파일 사용)
* **잘못된 파일 이름(400):** 파일 이름이 길이 요구 사항(1-255자)을 충족하지 않거나 금지된 문자(`<`, `>`, `:`, `"`, `|`, `?`, `*`, `\`, `/`, 또는 유니코드 문자 0-31)를 포함합니다
* **파일이 너무 큼(413):** 파일이 500 MB 제한을 초과합니다
* **저장 제한 초과(400):** 조직이 1 TB 저장 제한에 도달했습니다

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

## 사용량 및 청구

Files API 작업은 무료입니다:

* 파일 업로드
* 파일 다운로드
* 파일 목록 조회
* 파일 메타데이터 가져오기
* 파일 삭제

Messages 요청에서 사용되는 파일 콘텐츠는 입력 토큰으로 가격이 책정됩니다.

### 속도 제한

파일 관련 API 호출은 분당 약 500개의 요청으로 제한됩니다. 더 높은 제한을 요청하려면 [영업팀에 문의](mailto:sales@anthropic.com)하세요.

## 다음 단계

<CardGroup cols={3}>
  <Card title="PDF 지원" icon="file" href="https://platform.claude.com/docs/ko/build-with-claude/pdf-support">
    Claude로 PDF를 처리하세요. 텍스트를 추출하고, 차트를 분석하고, 문서의 시각적 콘텐츠를 이해하세요.
  </Card>

  <Card title="코드 실행 도구" icon="terminal" href="https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool">
    샌드박스 컨테이너에서 Python 및 bash 코드를 실행하여 데이터를 분석하고, 파일을 생성하고, 솔루션을 반복하세요.
  </Card>

  <Card title="Vision" icon="image" href="https://platform.claude.com/docs/ko/build-with-claude/vision">
    시각적 입력을 처리 및 분석하고 이미지에서 텍스트와 코드를 생성하세요.
  </Card>
</CardGroup>