SPB Git

Repository Public

vision.md 46.6 KB 1,378 lines markdown

1---2title: Vision3url: https://platform.claude.com/docs/en/build-with-claude/vision4description: Claude's vision capabilities allow it to understand and analyze images, opening up exciting possibilities for multimodal interaction.5---67This guide describes how to send images to Claude, the limits and costs that apply, and where to find guidance for [coordinate-based workflows](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates).89***1011## Send images to Claude1213Use Claude's vision capabilities through:1415* [claude.ai](https://claude.ai/). Upload an image like you would a file, or drag and drop an image directly into the chat window.16* [Playground](https://platform.claude.com/playground) in the Claude Console. Add images directly to any User message block.17* API request. See the following examples.1819On the API, provide images to Claude as `image` content blocks using one of three source types:20211. A base64-encoded image embedded in the request body222. A URL reference to an image hosted online233. A `file_id` returned by the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) (upload once, reference many times)2425<Note>26  On Amazon Bedrock and Google Cloud, only base64-encoded sources are currently available.27</Note>2829<Tip>30  Just as [placing long documents before your query](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#long-context-prompting) improves results in text prompts, Claude works best when images come before text. Images placed after text or interpolated with text still perform well, but if your use case allows it, prefer an image-then-text structure.31</Tip>3233### Base64-encoded image example3435<CodeGroup>36  ```bash cURL37  curl https://api.anthropic.com/v1/messages \38    -H "x-api-key: $ANTHROPIC_API_KEY" \39    -H "anthropic-version: 2023-06-01" \40    -H "content-type: application/json" \41    -d @- <<EOF42  {43    "model": "claude-opus-5",44    "max_tokens": 1024,45    "messages": [46      {47        "role": "user",48        "content": [49          {50            "type": "image",51            "source": {52              "type": "base64",53              "media_type": "image/jpeg",54              "data": "$BASE64_IMAGE_DATA"55            }56          },57          {58            "type": "text",59            "text": "Describe this image."60          }61        ]62      }63    ]64  }65  EOF66  ```6768  ```bash CLI69  curl -sSo ./vision-example.jpg \70    https://platform.claude.com/docs/images/vision-example.jpg7172  ant messages create <<'YAML'73  model: claude-opus-574  max_tokens: 102475  messages:76    - role: user77      content:78        - type: image79          source:80            type: base6481            media_type: image/jpeg82            data: "@./vision-example.jpg"83        - type: text84          text: Describe this image.85  YAML86  ```8788  ```python Python89  image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"90  image1_media_type = "image/png"9192  client = anthropic.Anthropic()93  message = client.messages.create(94      model="claude-opus-5",95      max_tokens=1024,96      messages=[97          {98              "role": "user",99              "content": [100                  {101                      "type": "image",102                      "source": {103                          "type": "base64",104                          "media_type": image1_media_type,105                          "data": image1_data,106                      },107                  },108                  {"type": "text", "text": "Describe this image."},109              ],110          }111      ],112  )113  print(message)114  ```115116  ```typescript TypeScript117  const anthropic = new Anthropic();118119  const message = await anthropic.messages.create({120    model: "claude-opus-5",121    max_tokens: 1024,122    messages: [123      {124        role: "user",125        content: [126          {127            type: "image",128            source: {129              type: "base64",130              media_type: "image/jpeg",131              data: imageData // Base64-encoded image data as string132            }133          },134          {135            type: "text",136            text: "Describe this image."137          }138        ]139      }140    ]141  });142143  console.log(message);144  ```145146  ```csharp C#147  using System.Collections.Generic;148  using Anthropic;149  using Anthropic.Models.Messages;150151  AnthropicClient client = new();152153  string imageData = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";154155  var message = await client.Messages.Create(new MessageCreateParams156  {157      Model = Model.ClaudeOpus5,158      MaxTokens = 1024,159      Messages =160      [161          new()162          {163              Role = Role.User,164              Content = new MessageParamContent(new List<ContentBlockParam>165              {166                  new ContentBlockParam(new ImageBlockParam(167                      new ImageBlockParamSource(new Base64ImageSource()168                      {169                          Data = imageData,170                          MediaType = MediaType.ImagePng,171                      })172                  )),173                  new ContentBlockParam(new TextBlockParam("Describe this image.")),174              }),175          }176      ]177  });178179  Console.WriteLine(message);180  ```181182  ```go Go183  client := anthropic.NewClient()184185  imageData := "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"186187  message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{188  	Model:     anthropic.ModelClaudeOpus5,189  	MaxTokens: 1024,190  	Messages: []anthropic.MessageParam{191  		anthropic.NewUserMessage(192  			anthropic.NewImageBlockBase64("image/png", imageData),193  			anthropic.NewTextBlock("Describe this image."),194  		),195  	},196  })197  if err != nil {198  	log.Fatal(err)199  }200201  fmt.Println(message)202  ```203204  ```java Java205  AnthropicClient client = AnthropicOkHttpClient.fromEnv();206  String imageData =207    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";208209  List<ContentBlockParam> contentBlockParams = List.of(210    ContentBlockParam.ofImage(211      ImageBlockParam.builder()212        .source(213          Base64ImageSource.builder()214            .mediaType(Base64ImageSource.MediaType.IMAGE_PNG)215            .data(imageData)216            .build()217        )218        .build()219    ),220    ContentBlockParam.ofText(TextBlockParam.builder().text("Describe this image.").build())221  );222  Message message = client223    .messages()224    .create(225      MessageCreateParams.builder()226        .model(Model.CLAUDE_OPUS_5)227        .maxTokens(1024)228        .addUserMessageOfBlockParams(contentBlockParams)229        .build()230    );231232  IO.println(message);233  ```234235  ```php PHP236  $client = new Client();237238  $imageData = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";239240  $message = $client->messages->create(241      maxTokens: 1024,242      messages: [243          [244              'role' => 'user',245              'content' => [246                  [247                      'type' => 'image',248                      'source' => [249                          'type' => 'base64',250                          'media_type' => 'image/png',251                          'data' => $imageData,252                      ],253                  ],254                  ['type' => 'text', 'text' => 'Describe this image.'],255              ],256          ],257      ],258      model: 'claude-opus-5',259  );260261  echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;262  ```263264  ```ruby Ruby265  client = Anthropic::Client.new266267  image_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"268269  message = client.messages.create(270    model: "claude-opus-5",271    max_tokens: 1024,272    messages: [273      {274        role: "user",275        content: [276          {277            type: "image",278            source: {279              type: "base64",280              media_type: "image/png",281              data: image_data282            }283          },284          { type: "text", text: "Describe this image." }285        ]286      }287    ]288  )289290  puts message291  ```292</CodeGroup>293294### URL-based image example295296<CodeGroup>297  ```bash cURL298  curl https://api.anthropic.com/v1/messages \299    -H "x-api-key: $ANTHROPIC_API_KEY" \300    -H "anthropic-version: 2023-06-01" \301    -H "content-type: application/json" \302    -d '{303      "model": "claude-opus-5",304      "max_tokens": 1024,305      "messages": [306        {307          "role": "user",308          "content": [309            {310              "type": "image",311              "source": {312                "type": "url",313                "url": "https://platform.claude.com/docs/images/vision-example.jpg"314              }315            },316            {317              "type": "text",318              "text": "Describe this image."319            }320          ]321        }322      ]323    }'324  ```325326  ```bash CLI327  ant messages create <<'YAML'328  model: claude-opus-5329  max_tokens: 1024330  messages:331    - role: user332      content:333        - type: image334          source:335            type: url336            url: https://platform.claude.com/docs/images/vision-example.jpg337        - type: text338          text: Describe this image.339  YAML340  ```341342  ```python Python343  client = anthropic.Anthropic()344  message = client.messages.create(345      model="claude-opus-5",346      max_tokens=1024,347      messages=[348          {349              "role": "user",350              "content": [351                  {352                      "type": "image",353                      "source": {354                          "type": "url",355                          "url": "https://platform.claude.com/docs/images/vision-example.jpg",356                      },357                  },358                  {"type": "text", "text": "Describe this image."},359              ],360          }361      ],362  )363  print(message)364  ```365366  ```typescript TypeScript367  const anthropic = new Anthropic();368369  const message = await anthropic.messages.create({370    model: "claude-opus-5",371    max_tokens: 1024,372    messages: [373      {374        role: "user",375        content: [376          {377            type: "image",378            source: {379              type: "url",380              url: "https://platform.claude.com/docs/images/vision-example.jpg"381            }382          },383          {384            type: "text",385            text: "Describe this image."386          }387        ]388      }389    ]390  });391392  console.log(message);393  ```394395  ```csharp C#396  using System.Collections.Generic;397  using Anthropic;398  using Anthropic.Models.Messages;399400  AnthropicClient client = new();401402  var message = await client.Messages.Create(new MessageCreateParams403  {404      Model = Model.ClaudeOpus5,405      MaxTokens = 1024,406      Messages =407      [408          new()409          {410              Role = Role.User,411              Content = new MessageParamContent(new List<ContentBlockParam>412              {413                  new ContentBlockParam(new ImageBlockParam(414                      new ImageBlockParamSource(new UrlImageSource()415                      {416                          Url = "https://platform.claude.com/docs/images/vision-example.jpg",417                      })418                  )),419                  new ContentBlockParam(new TextBlockParam("Describe this image.")),420              }),421          }422      ]423  });424425  Console.WriteLine(message);426  ```427428  ```go Go429  client := anthropic.NewClient()430431  message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{432  	Model:     anthropic.ModelClaudeOpus5,433  	MaxTokens: 1024,434  	Messages: []anthropic.MessageParam{435  		anthropic.NewUserMessage(436  			anthropic.NewImageBlock(anthropic.URLImageSourceParam{437  				URL: "https://platform.claude.com/docs/images/vision-example.jpg",438  			}),439  			anthropic.NewTextBlock("Describe this image."),440  		),441  	},442  })443  if err != nil {444  	log.Fatal(err)445  }446447  fmt.Println(message)448  ```449450  ```java Java451  AnthropicClient client = AnthropicOkHttpClient.fromEnv();452453  List<ContentBlockParam> contentBlockParams = List.of(454    ContentBlockParam.ofImage(455      ImageBlockParam.builder()456        .source(457          UrlImageSource.builder()458            .url("https://platform.claude.com/docs/images/vision-example.jpg")459            .build()460        )461        .build()462    ),463    ContentBlockParam.ofText(TextBlockParam.builder().text("Describe this image.").build())464  );465  Message message = client466    .messages()467    .create(468      MessageCreateParams.builder()469        .model(Model.CLAUDE_OPUS_5)470        .maxTokens(1024)471        .addUserMessageOfBlockParams(contentBlockParams)472        .build()473    );474  System.out.println(message);475  ```476477  ```php PHP478  $client = new Client();479480  $message = $client->messages->create(481      maxTokens: 1024,482      messages: [483          [484              'role' => 'user',485              'content' => [486                  [487                      'type' => 'image',488                      'source' => [489                          'type' => 'url',490                          'url' => 'https://platform.claude.com/docs/images/vision-example.jpg',491                      ],492                  ],493                  ['type' => 'text', 'text' => 'Describe this image.'],494              ],495          ],496      ],497      model: 'claude-opus-5',498  );499500  echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;501  ```502503  ```ruby Ruby504  client = Anthropic::Client.new505506  message = client.messages.create(507    model: "claude-opus-5",508    max_tokens: 1024,509    messages: [510      {511        role: "user",512        content: [513          {514            type: "image",515            source: {516              type: "url",517              url: "https://platform.claude.com/docs/images/vision-example.jpg"518            }519          },520          { type: "text", text: "Describe this image." }521        ]522      }523    ]524  )525526  puts message527  ```528</CodeGroup>529530### Files API image example531532For images you'll use repeatedly or when you want to avoid encoding overhead, use the [Files API](https://platform.claude.com/docs/en/build-with-claude/files). Upload the image once, then reference the returned `file_id` in subsequent messages instead of resending base64 data.533534<Tip>535  In multi-turn conversations and agentic workflows, each request resends the full conversation history. If images are base64-encoded, the full image bytes are included in the payload on every turn, which can significantly increase request size and latency as the conversation grows. Uploading images to the Files API and referencing them by `file_id` keeps request payloads small regardless of how many images accumulate in the conversation history.536</Tip>537538<CodeGroup>539  ```bash cURL540  # First, upload your image to the Files API541  FILE_ID=$(curl -sS -X POST https://api.anthropic.com/v1/files \542    -H "x-api-key: $ANTHROPIC_API_KEY" \543    -H "anthropic-version: 2023-06-01" \544    -F "file=@vision-example.jpg" | jq -r '.id')545546  # Then use the returned file_id in your message547  curl https://api.anthropic.com/v1/messages \548    -H "x-api-key: $ANTHROPIC_API_KEY" \549    -H "anthropic-version: 2023-06-01" \550    -H "content-type: application/json" \551    -d @- <<EOF552  {553    "model": "claude-opus-5",554    "max_tokens": 1024,555    "messages": [556      {557        "role": "user",558        "content": [559          {560            "type": "image",561            "source": {562              "type": "file",563              "file_id": "$FILE_ID"564            }565          },566          {567            "type": "text",568            "text": "Describe this image."569          }570        ]571      }572    ]573  }574  EOF575  ```576577  ```bash CLI578  curl -sSo vision-example.jpg \579    https://platform.claude.com/docs/images/vision-example.jpg580581  # First, upload your image to the Files API582  FILE_ID=$(ant files upload \583    --file ./vision-example.jpg \584    --transform id --raw-output)585586  # Then use the returned file_id in your message587  ant messages create \588    --transform content --format yaml <<YAML589  model: claude-opus-5590  max_tokens: 1024591  messages:592    - role: user593      content:594        - type: image595          source:596            type: file597            file_id: $FILE_ID598        - type: text599          text: Describe this image.600  YAML601  ```602603  ```python Python604  client = anthropic.Anthropic()605606  # Upload the image file607  with open("vision-example.jpg", "rb") as f:608      file_upload = client.files.upload(file=("vision-example.jpg", f, "image/jpeg"))609610  # Use the uploaded file in a message611  message = client.messages.create(612      model="claude-opus-5",613      max_tokens=1024,614      messages=[615          {616              "role": "user",617              "content": [618                  {619                      "type": "image",620                      "source": {"type": "file", "file_id": file_upload.id},621                  },622                  {"type": "text", "text": "Describe this image."},623              ],624          }625      ],626  )627628  print(message.content)629  ```630631  ```typescript TypeScript632  import Anthropic, { toFile } from "@anthropic-ai/sdk";633  import fs from "node:fs";634635  const anthropic = new Anthropic();636637  // Upload the image file638  const fileUpload = await anthropic.files.upload({639    file: await toFile(fs.createReadStream("vision-example.jpg"), undefined, {640      type: "image/jpeg"641    })642  });643644  // Use the uploaded file in a message645  const response = await anthropic.messages.create({646    model: "claude-opus-5",647    max_tokens: 1024,648    messages: [649      {650        role: "user",651        content: [652          {653            type: "image",654            source: {655              type: "file",656              file_id: fileUpload.id657            }658          },659          {660            type: "text",661            text: "Describe this image."662          }663        ]664      }665    ]666  });667668  console.log(response);669  ```670671  ```csharp C#672  using System.Collections.Generic;673  using Anthropic;674  using Anthropic.Core;675  using Anthropic.Models.Files;676  using Anthropic.Models.Messages;677678  AnthropicClient client = new();679680  // Upload the image file681  var fileUpload = await client.Files.Upload(new FileUploadParams682  {683      File = new BinaryContent684      {685          Stream = File.OpenRead("vision-example.jpg"),686          FileName = "vision-example.jpg",687          ContentType = new("image/jpeg"),688      },689  });690691  // Use the uploaded file in a message692  var response = await client.Messages.Create(new MessageCreateParams693  {694      Model = Model.ClaudeOpus5,695      MaxTokens = 1024,696      Messages =697      [698          new()699          {700              Role = Role.User,701              Content = new MessageParamContent(new List<ContentBlockParam>702              {703                  new ContentBlockParam(new ImageBlockParam(704                      new ImageBlockParamSource(new FileImageSource(fileUpload.ID))705                  )),706                  new ContentBlockParam(new TextBlockParam("Describe this image.")),707              }),708          }709      ]710  });711712  Console.WriteLine(response);713  ```714715  ```go Go716  client := anthropic.NewClient()717718  // Upload the image file719  file, err := os.Open("vision-example.jpg")720  if err != nil {721  	log.Fatal(err)722  }723  defer file.Close()724725  fileUpload, err := client.Files.Upload(context.Background(),726  	anthropic.FileUploadParams{727  		File: anthropic.File(file, "vision-example.jpg", "image/jpeg"),728  	})729  if err != nil {730  	log.Fatal(err)731  }732733  // Use the uploaded file in a message734  message, err := client.Messages.New(context.Background(),735  	anthropic.MessageNewParams{736  		Model:     anthropic.ModelClaudeOpus5,737  		MaxTokens: 1024,738  		Messages: []anthropic.MessageParam{739  			anthropic.NewUserMessage(740  				anthropic.NewImageBlock(anthropic.FileImageSourceParam{741  					FileID: fileUpload.ID,742  				}),743  				anthropic.NewTextBlock("Describe this image."),744  			),745  		},746  	})747  if err != nil {748  	log.Fatal(err)749  }750751  fmt.Println(message.Content)752  ```753754  ```java Java755  import com.anthropic.core.MultipartField;756  import com.anthropic.models.files.FileMetadata;757  import com.anthropic.models.files.FileUploadParams;758  // ...759      AnthropicClient client = AnthropicOkHttpClient.fromEnv();760761      // Upload the image file762      FileMetadata file = client.files().upload(763        FileUploadParams.builder()764          .file(765            MultipartField.<InputStream>builder()766              .value(Files.newInputStream(Path.of("vision-example.jpg")))767              .filename("vision-example.jpg")768              .contentType("image/jpeg")769              .build()770          )771          .build()772      );773774      // Use the uploaded file in a message775      ImageBlockParam imageParam = ImageBlockParam.builder().fileSource(file.id()).build();776777      MessageCreateParams params = MessageCreateParams.builder()778        .model(Model.CLAUDE_OPUS_5)779        .maxTokens(1024)780        .addUserMessageOfBlockParams(781          List.of(782            ContentBlockParam.ofImage(imageParam),783            ContentBlockParam.ofText(784              TextBlockParam.builder().text("Describe this image.").build()785            )786          )787        )788        .build();789790      Message message = client.messages().create(params);791      System.out.println(message.content());792  ```793794  ```php PHP795  use Anthropic\Core\FileParam;796797  $client = new Client();798799  // Upload the image file800  $fileUpload = $client->files->upload(801      file: FileParam::fromResource(fopen('vision-example.jpg', 'rb'), contentType: 'image/jpeg'),802  );803804  // Use the uploaded file in a message805  $message = $client->messages->create(806      maxTokens: 1024,807      messages: [808          [809              'role' => 'user',810              'content' => [811                  [812                      'type' => 'image',813                      'source' => ['type' => 'file', 'fileID' => $fileUpload->id],814                  ],815                  ['type' => 'text', 'text' => 'Describe this image.'],816              ],817          ],818      ],819      model: 'claude-opus-5',820  );821822  echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;823  ```824825  ```ruby Ruby826  client = Anthropic::Client.new827828  # Upload the image file829  file_upload = client.files.upload(830    file: Anthropic::FilePart.new(831      File.open("vision-example.jpg", "rb"),832      content_type: "image/jpeg"833    )834  )835836  # Use the uploaded file in a message837  message = client.messages.create(838    model: "claude-opus-5",839    max_tokens: 1024,840    messages: [841      {842        role: "user",843        content: [844          {845            type: "image",846            source: { type: "file", file_id: file_upload.id }847          },848          { type: "text", text: "Describe this image." }849        ]850      }851    ]852  )853854  puts message.content855  ```856</CodeGroup>857858See [Messages API examples](https://platform.claude.com/docs/en/api/messages/create) for more example code and parameter details.859860### Multiple images861862You can include multiple images in a single request, and Claude analyzes them jointly. This is useful for comparing images, asking about differences, or working with a sequence such as pages of a document. When sending several images, introduce each one with a short text label (`Image 1:`, `Image 2:`, and so on) so you can refer to them by name in your prompt and in follow-up turns.863864<CodeGroup>865  ```bash cURL866  curl https://api.anthropic.com/v1/messages \867    -H "x-api-key: $ANTHROPIC_API_KEY" \868    -H "anthropic-version: 2023-06-01" \869    -H "content-type: application/json" \870    -d '{871      "model": "claude-opus-5",872      "max_tokens": 1024,873      "messages": [874        {875          "role": "user",876          "content": [877            {878              "type": "text",879              "text": "Image 1:"880            },881            {882              "type": "image",883              "source": {884                "type": "base64",885                "media_type": "image/png",886                "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"887              }888            },889            {890              "type": "text",891              "text": "Image 2:"892            },893            {894              "type": "image",895              "source": {896                "type": "base64",897                "media_type": "image/png",898                "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"899              }900            },901            {902              "type": "text",903              "text": "How are these images different?"904            }905          ]906        }907      ]908    }'909  ```910911  ```bash CLI912  ant messages create <<'YAML'913  model: claude-opus-5914  max_tokens: 1024915  messages:916    - role: user917      content:918        - type: text919          text: "Image 1:"920        - type: image921          source:922            type: base64923            media_type: image/png924            data: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC925        - type: text926          text: "Image 2:"927        - type: image928          source:929            type: base64930            media_type: image/png931            data: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC932        - type: text933          text: How are these images different?934  YAML935  ```936937  ```python Python938  image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"939  image2_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"940941  client = anthropic.Anthropic()942  message = client.messages.create(943      model="claude-opus-5",944      max_tokens=1024,945      messages=[946          {947              "role": "user",948              "content": [949                  {"type": "text", "text": "Image 1:"},950                  {951                      "type": "image",952                      "source": {953                          "type": "base64",954                          "media_type": "image/png",955                          "data": image1_data,956                      },957                  },958                  {"type": "text", "text": "Image 2:"},959                  {960                      "type": "image",961                      "source": {962                          "type": "base64",963                          "media_type": "image/png",964                          "data": image2_data,965                      },966                  },967                  {"type": "text", "text": "How are these images different?"},968              ],969          }970      ],971  )972  print(message)973  ```974975  ```typescript TypeScript976  const anthropic = new Anthropic();977978  const image1Data =979    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";980  const image2Data =981    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC";982983  const message = await anthropic.messages.create({984    model: "claude-opus-5",985    max_tokens: 1024,986    messages: [987      {988        role: "user",989        content: [990          {991            type: "text",992            text: "Image 1:"993          },994          {995            type: "image",996            source: {997              type: "base64",998              media_type: "image/png",999              data: image1Data1000            }1001          },1002          {1003            type: "text",1004            text: "Image 2:"1005          },1006          {1007            type: "image",1008            source: {1009              type: "base64",1010              media_type: "image/png",1011              data: image2Data1012            }1013          },1014          {1015            type: "text",1016            text: "How are these images different?"1017          }1018        ]1019      }1020    ]1021  });10221023  console.log(message);1024  ```10251026  ```csharp C#1027  AnthropicClient client = new();10281029  string image1Data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";1030  string image2Data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC";10311032  var message = await client.Messages.Create(new MessageCreateParams1033  {1034      Model = Model.ClaudeOpus5,1035      MaxTokens = 1024,1036      Messages =1037      [1038          new()1039          {1040              Role = Role.User,1041              Content = new MessageParamContent(new List<ContentBlockParam>1042              {1043                  new ContentBlockParam(new TextBlockParam("Image 1:")),1044                  new ContentBlockParam(new ImageBlockParam(1045                      new ImageBlockParamSource(new Base64ImageSource()1046                      {1047                          Data = image1Data,1048                          MediaType = MediaType.ImagePng,1049                      })1050                  )),1051                  new ContentBlockParam(new TextBlockParam("Image 2:")),1052                  new ContentBlockParam(new ImageBlockParam(1053                      new ImageBlockParamSource(new Base64ImageSource()1054                      {1055                          Data = image2Data,1056                          MediaType = MediaType.ImagePng,1057                      })1058                  )),1059                  new ContentBlockParam(new TextBlockParam("How are these images different?")),1060              }),1061          }1062      ]1063  });10641065  Console.WriteLine(message);1066  ```10671068  ```go Go1069  client := anthropic.NewClient()10701071  image1Data := "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"1072  image2Data := "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"10731074  message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{1075  	Model:     anthropic.ModelClaudeOpus5,1076  	MaxTokens: 1024,1077  	Messages: []anthropic.MessageParam{1078  		anthropic.NewUserMessage(1079  			anthropic.NewTextBlock("Image 1:"),1080  			anthropic.NewImageBlockBase64("image/png", image1Data),1081  			anthropic.NewTextBlock("Image 2:"),1082  			anthropic.NewImageBlockBase64("image/png", image2Data),1083  			anthropic.NewTextBlock("How are these images different?"),1084  		),1085  	},1086  })1087  if err != nil {1088  	log.Fatal(err)1089  }10901091  fmt.Println(message)1092  ```10931094  ```java Java1095  AnthropicClient client = AnthropicOkHttpClient.fromEnv();10961097  String image1Data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";1098  String image2Data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC";10991100  List<ContentBlockParam> contentBlockParams = List.of(1101      ContentBlockParam.ofText(TextBlockParam.builder().text("Image 1:").build()),1102      ContentBlockParam.ofImage(1103          ImageBlockParam.builder()1104              .source(1105                  Base64ImageSource.builder()1106                      .mediaType(Base64ImageSource.MediaType.IMAGE_PNG)1107                      .data(image1Data)1108                      .build()1109              )1110              .build()1111      ),1112      ContentBlockParam.ofText(TextBlockParam.builder().text("Image 2:").build()),1113      ContentBlockParam.ofImage(1114          ImageBlockParam.builder()1115              .source(1116                  Base64ImageSource.builder()1117                      .mediaType(Base64ImageSource.MediaType.IMAGE_PNG)1118                      .data(image2Data)1119                      .build()1120              )1121              .build()1122      ),1123      ContentBlockParam.ofText(1124          TextBlockParam.builder().text("How are these images different?").build()1125      )1126  );11271128  Message message = client1129      .messages()1130      .create(1131          MessageCreateParams.builder()1132              .model(Model.CLAUDE_OPUS_5)1133              .maxTokens(1024)1134              .addUserMessageOfBlockParams(contentBlockParams)1135              .build()1136      );11371138  IO.println(message);1139  ```11401141  ```php PHP1142  $client = new Client();11431144  $image1Data = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC';1145  $image2Data = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC';11461147  $message = $client->messages->create(1148      maxTokens: 1024,1149      messages: [1150          [1151              'role' => 'user',1152              'content' => [1153                  ['type' => 'text', 'text' => 'Image 1:'],1154                  [1155                      'type' => 'image',1156                      'source' => [1157                          'type' => 'base64',1158                          'media_type' => 'image/png',1159                          'data' => $image1Data,1160                      ],1161                  ],1162                  ['type' => 'text', 'text' => 'Image 2:'],1163                  [1164                      'type' => 'image',1165                      'source' => [1166                          'type' => 'base64',1167                          'media_type' => 'image/png',1168                          'data' => $image2Data,1169                      ],1170                  ],1171                  ['type' => 'text', 'text' => 'How are these images different?'],1172              ],1173          ],1174      ],1175      model: 'claude-opus-5',1176  );11771178  echo $message;1179  ```11801181  ```ruby Ruby1182  client = Anthropic::Client.new11831184  image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"1185  image2_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGNgYPgPAAEDAQAIicLsAAAAAElFTkSuQmCC"11861187  message = client.messages.create(1188    model: "claude-opus-5",1189    max_tokens: 1024,1190    messages: [1191      {1192        role: "user",1193        content: [1194          { type: "text", text: "Image 1:" },1195          {1196            type: "image",1197            source: {1198              type: "base64",1199              media_type: "image/png",1200              data: image1_data1201            }1202          },1203          { type: "text", text: "Image 2:" },1204          {1205            type: "image",1206            source: {1207              type: "base64",1208              media_type: "image/png",1209              data: image2_data1210            }1211          },1212          { type: "text", text: "How are these images different?" }1213        ]1214      }1215    ]1216  )12171218  puts message1219  ```1220</CodeGroup>12211222In a multi-turn conversation, add new images in later `user` turns the same way. Claude has access to every image from earlier turns, so follow-up questions such as "Are these similar to the first two?" work without including the earlier images again in the new turn's content.12231224***12251226## Image limits and costs12271228### Request limits12291230The maximum number of images per message or request is:12311232* 20 per message on [claude.ai](https://claude.ai/).1233* 100 per request on the API, for models with a 200k-token context window.1234* 600 per request on the API, for all other models.12351236The maximum dimensions per image are 8000x8000 px.12371238If a single API request contains more than 20 images, a stricter per-image dimension limit applies to every image in that request. All `image` blocks in the request count toward this threshold, including images from earlier conversation turns that you resend and images nested inside `tool_result` content (for example, screenshots returned to the computer use tool). On Amazon Bedrock and Google Cloud, document blocks such as PDFs also count toward this threshold. Images exceeding the stricter limit are rejected with an `invalid_request_error` whose message references "many-image requests" and states the current limit in pixels. To stay under the limit on all platforms, either resize each image so that neither dimension exceeds 2000 px, or keep the request to 20 or fewer image and document blocks.12391240The maximum size per image is:12411242* 10 MB (base64-encoded) when using the Claude API directly.1243* 5 MB (base64-encoded) on Amazon Bedrock and Google Cloud.1244* 10 MB on [claude.ai](https://claude.ai/).12451246<Note>1247  Although the API supports up to 600 images per request, [request size limits](https://platform.claude.com/docs/en/api/overview#request-size-limits) (32 MB for standard endpoints; lower on some partner-operated platforms, for example, Amazon Bedrock and Google Cloud) can be reached first. For many images, consider uploading with the [Files API](https://platform.claude.com/docs/en/build-with-claude/vision#files-api-image-example) and referencing by `file_id` to keep request payloads small.12481249  Even when using the Files API, requests with many large images can fail before reaching the 600-image count. Reduce image dimensions or file sizes (for example, by downsampling) before uploading (see [Resolution and token cost](https://platform.claude.com/docs/en/build-with-claude/vision#evaluate-image-size)).1250</Note>12511252### Supported formats12531254Claude supports JPEG, PNG, GIF, and WebP images (`image/jpeg`, `image/png`, `image/gif`, `image/webp`). Animations are unsupported, and only the first frame is used.12551256### Resolution and token cost12571258Claude views images in patches instead of pixels. Each patch is a 28×28-pixel block of the image, referred to as a visual token. An image, therefore, costs `⌈width / 28⌉ × ⌈height / 28⌉` visual tokens.12591260Each model has a maximum native image resolution, expressed as a long-edge limit and a visual-token limit. Images larger than either limit are downscaled before processing; see [How Claude resizes and pads images](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images) for the exact rule. The exception is screenshots and zoom images that you return to the [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions) and [browser use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool#targets-and-coordinates) toolsets: the API rejects a `tool_result` image that exceeds the model's limits with a validation error instead of downscaling it, so resize those images in your application before returning them. To have any other oversized image rejected with an error instead of downscaled, set the image block's [`transformations` field](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error).12611262| Resolution tier | Models                      | Max long edge | Max visual tokens |1263| --------------- | --------------------------- | ------------- | ----------------- |1264| High-resolution | Claude 4.7 and later models | 2576 px       | 4784              |1265| Standard        | All other models            | 1568 px       | 1568              |12661267High-resolution support is automatic on the listed models and requires no beta header or client-side opt-in.12681269The following table shows the downsized resolution and visual-token cost for several image sizes on each tier:12701271| Image size                     | Standard tier: downsized to | Standard tier: tokens | High-resolution tier: downsized to | High-resolution tier: tokens |1272| ------------------------------ | --------------------------- | --------------------- | ---------------------------------- | ---------------------------- |1273| 200x200 px (0.04 megapixels)   | Not resized                 | 64                    | Not resized                        | 64                           |1274| 1000x1000 px (1 megapixel)     | Not resized                 | 1296                  | Not resized                        | 1296                         |1275| 1092x1092 px (1.19 megapixels) | Not resized                 | 1521                  | Not resized                        | 1521                         |1276| 1920x1080 px (2.07 megapixels) | 1456x819 px                 | 1560                  | Not resized                        | 2691                         |1277| 2000x1500 px (3 megapixels)    | 1269x952 px                 | 1564                  | Not resized                        | 3888                         |1278| 3840x2160 px (8.29 megapixels) | 1456x819 px                 | 1560                  | 2576x1449 px                       | 4784                         |12791280When an image is downsized, Claude scales it to the largest size that fits the tier's limits while preserving its aspect ratio. This caps the token cost. For the precise rule and a reference implementation, see [How Claude resizes and pads images](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#how-claude-resizes-and-pads-images).12811282To estimate cost, multiply the token count by the [per-token price of the model](https://claude.com/pricing) you're using. For example, at Claude Haiku 4.5's $1 USD per million input tokens (standard tier), the 1000×1000 image costs about $1.30 USD per thousand images. At Claude Opus 5's $5 USD per million (high-resolution tier), the same image costs about $6.48 USD per thousand and the 4K image about $23.92 USD per thousand.12831284High-resolution images can use up to roughly three times more visual tokens than the same image on a standard-tier model. If you don't need the additional fidelity that high resolution provides for computer use, screenshot understanding, and dense documents, downsample images before sending to control token costs. To minimize latency and to simplify [coordinate-based workflows](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates), prefer resizing images before uploading them.12851286### Image quality guidance12871288When providing images to Claude, keep the following in mind for best results:12891290* **Image clarity:** Ensure images are clear and not too blurry or pixelated.1291* **Text:** If the image contains important text, make sure it's legible and not too small. Avoid cropping out key visual context solely to enlarge the text.1292* **Resizing:** Take into account that your image might be resized if it is too large (see [Resolution and token cost](https://platform.claude.com/docs/en/build-with-claude/vision#evaluate-image-size)); this might, for example, make text less legible. Consider pre-resizing your images, cropping them, or both. To have an oversized image rejected with an error instead of resized (important for [coordinate workflows](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates)), mark the image block with [`"oversized_image": "error"`](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error).1293* **Image compression:** Compressing images before sending them, using a lossy format such as JPEG or WebP (lossy mode), can reduce latency by reducing the size of requests. However, this can introduce artifacts that are detrimental to model performance, especially when multiple compression passes are applied. For example, heavy JPEG compression can make text difficult to read. Confirm your compression settings are appropriate for the task by inspecting the actual images sent to the API.12941295***12961297## Coordinates and bounding boxes12981299For bounding boxes, points, and pixel coordinates, see [Coordinates and bounding boxes](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates). Claude returns absolute pixel coordinates relative to the image it sees after resizing; that guide covers how Claude resizes and pads images and how to pre-resize or rescale so coordinates line up with your original image.13001301***13021303## Limitations13041305Although Claude's image understanding capabilities are cutting-edge, there are some limitations to be aware of:13061307* **People identification:** Claude [cannot be used](https://www.anthropic.com/legal/aup) to name people in images and refuses to do so.1308* **Accuracy:** Claude might hallucinate or make mistakes when interpreting low-quality, rotated, or very small images under 200 pixels.1309* **Spatial reasoning:** Claude's coordinate and localization outputs are approximate. Follow the guidance in [Coordinates and bounding boxes](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates) and verify outputs before relying on them.1310* **Counting:** Claude can give approximate counts of objects in an image but might not always be precisely accurate, especially with large numbers of small objects.1311* **AI-generated images:** Claude cannot determine whether an image is AI-generated and might be incorrect if asked. Do not rely on it to detect fake or synthetic images.1312* **Inappropriate content:** Claude does not process inappropriate or explicit images that violate the [Acceptable Use Policy](https://www.anthropic.com/legal/aup).1313* **Healthcare applications:** Although Claude can analyze general medical images, it is not designed to interpret complex diagnostic scans such as CTs or MRIs. Claude's outputs should not be considered a substitute for professional medical advice or diagnosis.13141315Always carefully review and verify Claude's image interpretations, especially for high-stakes use cases. Do not use Claude for tasks requiring perfect precision or sensitive image analysis without human oversight.13161317***13181319## FAQ13201321<AccordionGroup>1322  <Accordion title="What image file types does Claude support?">1323    JPEG, PNG, GIF, and WebP. See [Supported formats](https://platform.claude.com/docs/en/build-with-claude/vision#supported-formats).1324  </Accordion>13251326  <Accordion title="Can Claude read image URLs?">1327    Yes. Use the `url` source type instead of `base64` in the `image` content block. See the [URL-based image example](https://platform.claude.com/docs/en/build-with-claude/vision#url-based-image-example).1328  </Accordion>13291330  <Accordion title="Is there a limit to the image file size I can upload?">1331    Yes. See [Request limits](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits) for per-image and overall request size limits across the Claude API, Amazon Bedrock, Google Cloud, and claude.ai.1332  </Accordion>13331334  <Accordion title="How many images can I include in one request?">1335    Up to 600 per API request (100 for models with a 200k-token context window) and 20 per turn on claude.ai. See [Request limits](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits) for details and the lower per-image dimension limit that applies above 20 images.1336  </Accordion>13371338  <Accordion title="Does Claude read image metadata?">1339    No, Claude does not parse or receive any metadata from images passed to it.1340  </Accordion>13411342  <Accordion title="Can I delete images I've uploaded?">1343    No. Image uploads are ephemeral and not stored beyond the duration of the API request. Uploaded images are automatically deleted after they have been processed.1344  </Accordion>13451346  <Accordion title="Where can I find details on data privacy for image uploads?">1347    Refer to the Anthropic privacy policy page for information on how uploaded images and other data are handled. Anthropic does not use uploaded images to train models.1348  </Accordion>13491350  <Accordion title="What if Claude's image interpretation seems wrong?">1351    If Claude's image interpretation seems incorrect:13521353    1. Ensure the image is clear, high-quality, and correctly oriented.1354    2. Try prompt engineering techniques to improve results.1355    3. If the issue persists, flag the output in claude.ai (thumbs up/down) or contact the [support team](https://support.claude.com/).13561357    Your feedback helps improve Claude!1358  </Accordion>13591360  <Accordion title="Can Claude generate or edit images?">1361    No, Claude is an image understanding model only. It can interpret and analyze images, but it cannot generate, produce, edit, manipulate, or create images.1362  </Accordion>1363</AccordionGroup>13641365***13661367## Next steps13681369<CardGroup cols={2}>1370  <Card title="Multimodal cookbook" icon="image" href="https://platform.claude.com/cookbook/multimodal-getting-started-with-vision">1371    Get tips and best-practice techniques for tasks such as interpreting charts and extracting content from forms.1372  </Card>13731374  <Card title="API reference" icon="code" href="https://platform.claude.com/docs/en/api/messages/create">1375    See the Messages API documentation, including example API calls involving images.1376  </Card>1377</CardGroup>1378
Files main
Menu

Theme