Repository Public
1# Images and vision23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45## Overview6789 - **[Create images](https://developers.openai.com/api/docs/guides/image-generation)**: Use GPT Image models to generate or edit images.10- **[Process image inputs](#analyze-images)**: Use our models' vision capabilities to analyze images.11121314<a id="a-tour-of-image-related-use-cases"></a>1516Recent language models can process image inputs and analyze them—a capability known as **vision**. GPT Image models can use text and image inputs to create new images or edit existing ones.1718Choose an endpoint based on whether you want to analyze images or generate them:1920| API | Supported use cases |21| ---------------------------------------------------- | -------------------------------------------------------------------------- |22| [Responses API](https://developers.openai.com/api/reference/resources/responses) | Analyze images, or generate and edit images with the image generation tool |23| [Images API](https://developers.openai.com/api/reference/resources/images) | Generate images as output, optionally using images as input |24| [Chat Completions API](https://developers.openai.com/api/reference/resources/chat) | Analyze images and generate text responses |2526To learn more about the input and output modalities supported by our models, refer to our [models page](https://developers.openai.com/api/docs/models).2728## Generate or edit images2930With the Images API, choose `gpt-image-2.5-sunburst` to generate images from text or edit existing images. With the Responses API, choose a mainline model that supports the image generation tool; the tool handles GPT Image model selection.31323334Generate images with Responses3536```javascript37import OpenAI from "openai";38const openai = new OpenAI();3940const response = await openai.responses.create({41 model: "gpt-6-astra",42 input:43 "Generate an image of gray tabby cat hugging an otter with an orange scarf",44 tools: [{ type: "image_generation" }],45});4647// Save the image to a file48const imageData = response.output49 .filter((output) => output.type === "image_generation_call")50 .map((output) => output.result);5152if (imageData.length > 0) {53 const imageBase64 = imageData[0];54 const fs = await import("fs");55 fs.writeFileSync("cat_and_otter.png", Buffer.from(imageBase64, "base64"));56}57```5859```python60from openai import OpenAI61import base646263client = OpenAI()6465response = client.responses.create(66 model="gpt-6-astra",67 input="Generate an image of gray tabby cat hugging an otter with an orange scarf",68 tools=[{"type": "image_generation"}],69)7071# Save the image to a file72image_data = [73 output.result74 for output in response.output75 if output.type == "image_generation_call"76]7778if image_data:79 image_base64 = image_data[0]80 with open("cat_and_otter.png", "wb") as f:81 f.write(base64.b64decode(image_base64))82```8384```go85package main8687import (88 "context"89 "encoding/base64"90 "os"9192 "github.com/openai/openai-go/v3"93 "github.com/openai/openai-go/v3/responses"94)9596func main() {97 client := openai.NewClient()9899 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{100 Model: "gpt-6-astra",101 Input: responses.ResponseNewParamsInputUnion{102 OfString: openai.String("Generate an image of a gray tabby cat hugging an otter with an orange scarf."),103 },104 Tools: []responses.ToolUnionParam{{105 OfImageGeneration: &responses.ToolImageGenerationParam{},106 }},107 })108 if err != nil {109 panic(err)110 }111112 for _, output := range response.Output {113 if output.Type != "image_generation_call" {114 continue115 }116 image, err := base64.StdEncoding.DecodeString(output.AsImageGenerationCall().Result)117 if err != nil {118 panic(err)119 }120 if err := os.WriteFile("cat_and_otter.png", image, 0o600); err != nil {121 panic(err)122 }123 return124 }125126 panic("response did not include an image generation call")127}128```129130```java131import com.openai.client.OpenAIClient;132import com.openai.client.okhttp.OpenAIOkHttpClient;133import com.openai.models.responses.ResponseCreateParams;134import com.openai.models.responses.Tool;135import java.io.IOException;136import java.nio.file.Files;137import java.nio.file.Path;138import java.util.Base64;139140ResponseCreateParams params =141 ResponseCreateParams.builder()142 .model("gpt-6-astra")143 .input("Generate an image of a gray tabby cat hugging an otter with an orange scarf.")144 .addTool(Tool.ImageGeneration.builder().build())145 .build();146147String imageResult =148 client.responses().create(params).output().stream()149 .flatMap(item -> item.imageGenerationCall().stream())150 .flatMap(call -> call.result().stream())151 .findFirst()152 .orElseThrow(() -> new IllegalStateException("No generated image returned"));153Files.write(Path.of("cat_and_otter.png"), Base64.getDecoder().decode(imageResult));154```155156```csharp157using OpenAI.Responses;158#pragma warning disable OPENAI001159160string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;161ResponsesClient client = new(key);162163CreateResponseOptions options = new()164{165 Model = "gpt-6-astra",166};167options.InputItems.Add(168 ResponseItem.CreateUserMessageItem(169 "Generate an image of a gray tabby cat hugging an otter with an orange scarf."170 )171);172options.Tools.Add(173 ResponseTool.CreateImageGenerationTool(model: "gpt-image-2")174);175176ResponseResult response = await client.CreateResponseAsync(options);177ImageGenerationCallResponseItem image = response178 .OutputItems.OfType<ImageGenerationCallResponseItem>()179 .FirstOrDefault()180 ?? throw new InvalidOperationException("No generated image was returned.");181await File.WriteAllBytesAsync(182 "cat_and_otter.png",183 image.ImageResultBytes.ToArray()184);185```186187```ruby188require "base64"189require "openai"190191client = OpenAI::Client.new192response = client.responses.create(193 model: "gpt-6-astra",194 input: "Generate an image of a gray tabby cat hugging an otter with an orange scarf.",195 tools: [{ type: :image_generation }]196)197198image_call = response.output.find do |item|199 item.is_a?(OpenAI::Models::Responses::ResponseOutputItem::ImageGenerationCall)200end201unless image_call.is_a?(OpenAI::Models::Responses::ResponseOutputItem::ImageGenerationCall)202 raise "No image generation call returned"203end204205File.binwrite(206 "cat_and_otter.png",207 Base64.strict_decode64(image_call.result)208)209```210211```bash212openai responses create \213 --model gpt-6-astra \214 --raw-output \215 --transform 'output.#(type=="image_generation_call").result' <<'YAML' | base64 --decode > cat_and_otter.png216tools:217 - type: image_generation218input: Generate an image of a gray tabby cat hugging an otter with an orange scarf.219YAML220```221222223224You can learn more about image generation in our [Image225 generation](https://developers.openai.com/api/docs/guides/image-generation) guide.226227### Using world knowledge for image generation228229GPT Image models can draw on world knowledge without a reference image. For example, a prompt for a cabinet of semi-precious stones can produce a scene containing recognizable gemstones such as amethyst, rose quartz, and jade.230231## Analyze images232233Use a vision-capable model to describe images, read visible text, and answer questions about objects, shapes, colors, or textures. Account for the model's [limitations](#limitations) when using its answers.234235### Giving a model images as input236237238239240241Provide an image for analysis in any of these ways:242243- By providing a fully qualified URL to an image file244- By providing an image as a Base64-encoded data URL245- By providing a file ID (created with the [Files API](https://developers.openai.com/api/reference/resources/files))246247You can provide multiple images as input in a single request by including multiple images in the `content` array, but keep in mind that [images count as tokens](#calculating-costs) and will be billed accordingly.248249250251Passing a URL252253 Analyze the content of an image254255```javascript256import OpenAI from "openai";257258const openai = new OpenAI();259260const response = await openai.responses.create({261 model: "gpt-6-astra",262 input: [263 {264 role: "user",265 content: [266 { type: "input_text", text: "what's in this image?" },267 {268 type: "input_image",269 image_url:270 "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg",271 detail: "auto",272 },273 ],274 },275 ],276});277278console.log(response.output_text);279```280281```python282from openai import OpenAI283284client = OpenAI()285286response = client.responses.create(287 model="gpt-6-astra",288 input=[289 {290 "role": "user",291 "content": [292 {"type": "input_text", "text": "what's in this image?"},293 {294 "type": "input_image",295 "image_url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg",296 },297 ],298 }299 ],300)301302print(response.output_text)303```304305```go306package main307308import (309 "context"310 "fmt"311312 "github.com/openai/openai-go/v3"313 "github.com/openai/openai-go/v3/responses"314)315316func main() {317 client := openai.NewClient()318319 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{320 Model: "gpt-6-astra",321 Input: responses.ResponseNewParamsInputUnion{322 OfInputItemList: responses.ResponseInputParam{323 responses.ResponseInputItemParamOfMessage(324 responses.ResponseInputMessageContentListParam{325 responses.ResponseInputContentParamOfInputText("What's in this image?"),326 {OfInputImage: &responses.ResponseInputImageParam{327 Detail: responses.ResponseInputImageDetailAuto,328 ImageURL: openai.String("https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg"),329 }},330 },331 responses.EasyInputMessageRoleUser,332 ),333 },334 },335 })336 if err != nil {337 panic(err)338 }339340 fmt.Println(response.OutputText())341}342```343344```java345import com.openai.client.OpenAIClient;346import com.openai.client.okhttp.OpenAIOkHttpClient;347import com.openai.models.responses.ResponseCreateParams;348import com.openai.models.responses.ResponseInputImage;349import com.openai.models.responses.ResponseInputItem;350import java.util.List;351352ResponseInputItem imageInput =353 ResponseInputItem.ofMessage(354 ResponseInputItem.Message.builder()355 .role(ResponseInputItem.Message.Role.USER)356 .addInputTextContent("What's in this image?")357 .addContent(358 ResponseInputImage.builder()359 .detail(ResponseInputImage.Detail.AUTO)360 .imageUrl(361 "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg")362 .build())363 .build());364365ResponseCreateParams params =366 ResponseCreateParams.builder()367 .model("gpt-6-astra")368 .inputOfResponse(List.of(imageInput))369 .build();370371client.responses().create(params).output().stream()372 .flatMap(item -> item.message().stream())373 .flatMap(message -> message.content().stream())374 .flatMap(content -> content.outputText().stream())375 .forEach(text -> System.out.println(text.text()));376```377378```csharp379using OpenAI.Responses;380#pragma warning disable OPENAI001381382string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;383ResponsesClient client = new(key);384385Uri imageUrl = new(386 "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg"387);388389ResponseResult response = await client.CreateResponseAsync(390 "gpt-6-astra",391 [392 ResponseItem.CreateUserMessageItem(393 [394 ResponseContentPart.CreateInputTextPart("What is in this image?"),395 ResponseContentPart.CreateInputImagePart(imageUrl),396 ]397 ),398 ]399);400401Console.WriteLine(response.GetOutputText());402```403404```ruby405require "openai"406407client = OpenAI::Client.new408409response = client.responses.create(410 model: "gpt-6-astra",411 input: [412 {413 role: :user,414 content: [415 {416 type: :input_text,417 text: "What's in this image?"418 },419 {420 type: :input_image,421 detail: :auto,422 image_url: "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg"423 }424 ]425 }426 ]427)428429puts(response.output_text)430```431432```bash433curl https://api.openai.com/v1/responses \434 -H "Content-Type: application/json" \435 -H "Authorization: Bearer $OPENAI_API_KEY" \436 -d '{437 "model": "gpt-6-astra",438 "input": [439 {440 "role": "user",441 "content": [442 {"type": "input_text", "text": "what is in this image?"},443 {444 "type": "input_image",445 "image_url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg"446 }447 ]448 }449 ]450 }'451```452453```bash454openai responses create \455 --model gpt-6-astra \456 --raw-output \457 --transform 'output.#(type=="message").content.0.text' <<'YAML'458input:459 - role: user460 content:461 - type: input_text462 text: What is in this image?463 - type: input_image464 image_url: https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg465YAML466```467468 469470 471472 473Passing a Base64 encoded image474475 Analyze the content of an image476477```javascript478import fs from "fs";479import OpenAI from "openai";480481const openai = new OpenAI();482483const imagePath = "fixtures/example.jpg";484const base64Image = fs.readFileSync(imagePath, "base64");485486const response = await openai.responses.create({487 model: "gpt-6-astra",488 input: [489 {490 role: "user",491 content: [492 { type: "input_text", text: "what's in this image?" },493 {494 type: "input_image",495 image_url: `data:image/jpeg;base64,${base64Image}`,496 detail: "auto",497 },498 ],499 },500 ],501});502503console.log(response.output_text);504```505506```python507import base64508from openai import OpenAI509510client = OpenAI()511512513# Function to encode the image514def encode_image(image_path):515 with open(image_path, "rb") as image_file:516 return base64.b64encode(image_file.read()).decode("utf-8")517518519# Path to your image520image_path = "path_to_your_image.jpg"521522# Getting the Base64 string523base64_image = encode_image(image_path)524525526response = client.responses.create(527 model="gpt-6-astra",528 input=[529 {530 "role": "user",531 "content": [532 {"type": "input_text", "text": "what's in this image?"},533 {534 "type": "input_image",535 "image_url": f"data:image/jpeg;base64,{base64_image}",536 },537 ],538 }539 ],540)541542print(response.output_text)543```544545```go546package main547548import (549 "context"550 "encoding/base64"551 "fmt"552 "os"553554 "github.com/openai/openai-go/v3"555 "github.com/openai/openai-go/v3/responses"556)557558func main() {559 client := openai.NewClient()560 image, err := os.ReadFile("image.png")561 if err != nil {562 panic(err)563 }564 imageURL := "data:image/png;base64," + base64.StdEncoding.EncodeToString(image)565566 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{567 Model: "gpt-6-astra",568 Input: responses.ResponseNewParamsInputUnion{569 OfInputItemList: responses.ResponseInputParam{570 responses.ResponseInputItemParamOfMessage(571 responses.ResponseInputMessageContentListParam{572 responses.ResponseInputContentParamOfInputText("What's in this image?"),573 {OfInputImage: &responses.ResponseInputImageParam{574 Detail: responses.ResponseInputImageDetailAuto,575 ImageURL: openai.String(imageURL),576 }},577 },578 responses.EasyInputMessageRoleUser,579 ),580 },581 },582 })583 if err != nil {584 panic(err)585 }586587 fmt.Println(response.OutputText())588}589```590591```java592import com.openai.client.OpenAIClient;593import com.openai.client.okhttp.OpenAIOkHttpClient;594import com.openai.models.responses.ResponseCreateParams;595import com.openai.models.responses.ResponseInputImage;596import com.openai.models.responses.ResponseInputItem;597import java.io.IOException;598import java.nio.file.Files;599import java.nio.file.Path;600import java.util.Base64;601import java.util.List;602603String imageBase64 =604 Base64.getEncoder()605 .encodeToString(606 Files.readAllBytes(Path.of(System.getenv("OPENAI_EXAMPLE_IMAGE_PATH"))));607608ResponseInputItem imageInput =609 ResponseInputItem.ofMessage(610 ResponseInputItem.Message.builder()611 .role(ResponseInputItem.Message.Role.USER)612 .addInputTextContent("What's in this image?")613 .addContent(614 ResponseInputImage.builder()615 .detail(ResponseInputImage.Detail.AUTO)616 .imageUrl("data:image/png;base64," + imageBase64)617 .build())618 .build());619620ResponseCreateParams params =621 ResponseCreateParams.builder()622 .model("gpt-6-astra")623 .inputOfResponse(List.of(imageInput))624 .build();625626client.responses().create(params).output().stream()627 .flatMap(item -> item.message().stream())628 .flatMap(message -> message.content().stream())629 .flatMap(content -> content.outputText().stream())630 .forEach(text -> System.out.println(text.text()));631```632633```csharp634using OpenAI.Responses;635#pragma warning disable OPENAI001636637string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;638ResponsesClient client = new(key);639640Uri imageUrl = new(641 "https://openai-documentation.vercel.app/images/cat_and_otter.png"642);643644using HttpClient http = new();645646// Download an image as a stream.647using Stream stream = await http.GetStreamAsync(imageUrl);648BinaryData imageData = BinaryData.FromStream(stream, "image/png");649650ResponseResult response1 = await client.CreateResponseAsync(651 "gpt-6-astra",652 [653 ResponseItem.CreateUserMessageItem(654 [655 ResponseContentPart.CreateInputTextPart("What is in this image?"),656 ResponseContentPart.CreateInputImagePart(imageData),657 ]658 ),659 ]660);661662Console.WriteLine($"From image stream: {response1.GetOutputText()}");663664// Download an image as a byte array.665byte[] bytes = await http.GetByteArrayAsync(imageUrl);666imageData = BinaryData.FromBytes(bytes, "image/png");667668ResponseResult response2 = await client.CreateResponseAsync(669 "gpt-6-astra",670 [671 ResponseItem.CreateUserMessageItem(672 [673 ResponseContentPart.CreateInputTextPart("What is in this image?"),674 ResponseContentPart.CreateInputImagePart(imageData),675 ]676 ),677 ]678);679680Console.WriteLine($"From byte array: {response2.GetOutputText()}");681```682683```ruby684require "base64"685require "openai"686687client = OpenAI::Client.new688image = Base64.strict_encode64(File.binread("image.png"))689690response = client.responses.create(691 model: "gpt-6-astra",692 input: [693 {694 role: :user,695 content: [696 {697 type: :input_text,698 text: "What's in this image?"699 },700 {701 type: :input_image,702 detail: :auto,703 image_url: "data:image/png;base64,#{image}"704 }705 ]706 }707 ]708)709710puts(response.output_text)711```712713 714715 716717 718Passing a file ID719720 Analyze the content of an image721722```javascript723import OpenAI from "openai";724import fs from "fs";725726const openai = new OpenAI();727728// Function to create a file with the Files API729async function createFile(filePath) {730 const fileContent = fs.createReadStream(filePath);731 const result = await openai.files.create({732 file: fileContent,733 purpose: "vision",734 });735 return result.id;736}737738// Getting the file ID739const fileId = await createFile("fixtures/example.jpg");740741const response = await openai.responses.create({742 model: "gpt-6-astra",743 input: [744 {745 role: "user",746 content: [747 { type: "input_text", text: "what's in this image?" },748 {749 type: "input_image",750 file_id: fileId,751 detail: "auto",752 },753 ],754 },755 ],756});757758console.log(response.output_text);759```760761```python762from openai import OpenAI763764client = OpenAI()765766767# Function to create a file with the Files API768def create_file(file_path):769 with open(file_path, "rb") as file_content:770 result = client.files.create(771 file=file_content,772 purpose="vision",773 )774 return result.id775776777# Getting the file ID778file_id = create_file("path_to_your_image.jpg")779780response = client.responses.create(781 model="gpt-6-astra",782 input=[783 {784 "role": "user",785 "content": [786 {"type": "input_text", "text": "what's in this image?"},787 {788 "type": "input_image",789 "file_id": file_id,790 },791 ],792 }793 ],794)795796print(response.output_text)797```798799```go800package main801802import (803 "context"804 "fmt"805 "os"806807 "github.com/openai/openai-go/v3"808 "github.com/openai/openai-go/v3/responses"809)810811func main() {812 client := openai.NewClient()813 file, err := os.Open("image.png")814 if err != nil {815 panic(err)816 }817 defer file.Close()818819 uploaded, err := client.Files.New(context.Background(), openai.FileNewParams{820 File: file,821 Purpose: openai.FilePurposeVision,822 })823 if err != nil {824 panic(err)825 }826827 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{828 Model: "gpt-6-astra",829 Input: responses.ResponseNewParamsInputUnion{830 OfInputItemList: responses.ResponseInputParam{831 responses.ResponseInputItemParamOfMessage(832 responses.ResponseInputMessageContentListParam{833 responses.ResponseInputContentParamOfInputText("What's in this image?"),834 {OfInputImage: &responses.ResponseInputImageParam{835 Detail: responses.ResponseInputImageDetailAuto,836 FileID: openai.String(uploaded.ID),837 }},838 },839 responses.EasyInputMessageRoleUser,840 ),841 },842 },843 })844 if err != nil {845 panic(err)846 }847848 fmt.Println(response.OutputText())849}850```851852```java853import com.openai.client.OpenAIClient;854import com.openai.client.okhttp.OpenAIOkHttpClient;855import com.openai.models.files.FileCreateParams;856import com.openai.models.files.FilePurpose;857import com.openai.models.responses.ResponseCreateParams;858import com.openai.models.responses.ResponseInputImage;859import com.openai.models.responses.ResponseInputItem;860import java.nio.file.Path;861import java.util.List;862863var file =864 client865 .files()866 .create(867 FileCreateParams.builder()868 .file(Path.of(System.getenv("OPENAI_EXAMPLE_FILE_PATH")))869 .purpose(FilePurpose.VISION)870 .build());871872var response =873 client874 .responses()875 .create(876 ResponseCreateParams.builder()877 .model("gpt-6-astra")878 .inputOfResponse(879 List.of(880 ResponseInputItem.ofMessage(881 ResponseInputItem.Message.builder()882 .role(ResponseInputItem.Message.Role.USER)883 .addInputTextContent("What's in this image?")884 .addContent(885 ResponseInputImage.builder()886 .detail(ResponseInputImage.Detail.AUTO)887 .fileId(file.id())888 .build())889 .build())))890 .build());891response.output().stream()892 .flatMap(item -> item.message().stream())893 .flatMap(message -> message.content().stream())894 .flatMap(content -> content.outputText().stream())895 .forEach(text -> System.out.println(text.text()));896```897898```csharp899using OpenAI.Files;900using OpenAI.Responses;901#pragma warning disable OPENAI001902903string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;904ResponsesClient client = new(key);905906string filename = "cat_and_otter.png";907Uri imageUrl = new(908 $"https://openai-documentation.vercel.app/images/{filename}"909);910911using HttpClient http = new();912913// Download an image as a stream.914using Stream stream = await http.GetStreamAsync(imageUrl);915916OpenAIFileClient files = new(key);917918OpenAIFile file = await files.UploadFileAsync(919 stream,920 filename,921 FileUploadPurpose.Vision922);923924ResponseResult response = await client.CreateResponseAsync(925 "gpt-6-astra",926 [927 ResponseItem.CreateUserMessageItem(928 [929 ResponseContentPart.CreateInputTextPart("what's in this image?"),930 ResponseContentPart.CreateInputImagePart(file.Id),931 ]932 ),933 ]934);935936Console.WriteLine(response.GetOutputText());937```938939```ruby940require "openai"941require "pathname"942943client = OpenAI::Client.new944uploaded = client.files.create(945 file: Pathname("image.png"),946 purpose: :vision947)948949response = client.responses.create(950 model: "gpt-6-astra",951 input: [952 {953 role: :user,954 content: [955 {956 type: :input_text,957 text: "What's in this image?"958 },959 {960 type: :input_image,961 detail: :auto,962 file_id: uploaded.id963 }964 ]965 }966 ]967)968969puts(response.output_text)970```971972973974975### Image input requirements976977Use supported image files that are clear enough for the model to analyze.978979| Requirement | Supported inputs |980| ------------ | ------------------------------------------------------------------------------------- |981| File types | PNG (`.png`), JPEG (`.jpeg` or `.jpg`), WEBP (`.webp`), and non-animated GIF (`.gif`) |982| Request size | Up to 512 MB total payload per request |983| Image count | Up to 1,500 images per request |984985For [patch-based image inputs](#patch-based-image-tokenization), the API supports up to 30,000 patches per image after applying the resizing rules for the selected model and `detail` level. This limit applies across supported detail levels and to each image separately, not to the combined patch count of the request.986987Lower model- and detail-specific resizing budgets still apply. Images that exceed the 30,000-patch limit after processing are rejected, not automatically resized to meet it. Reduce the image's dimensions and try again.988989Image tokens and the rest of your prompt must also fit the model's input and context limits. A token estimate does not guarantee that a request meets every input limit. Image use must comply with our [usage policies](https://openai.com/policies/usage-policies/).990991### Choose an image detail level992993The `detail` parameter controls image preprocessing. Supported values depend on the model: `low`, `high`, `original`, or `auto`. If you omit the parameter, it defaults to `auto` in both the Responses API and the Chat Completions API. The [model sizing table](#model-sizing-behavior) shows the corresponding behavior.994995996997998```plain999{1000 "type": "input_image",1001 "image_url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg",1002 "detail": "original"1003}1004```1005100610071008Use the following guidance to choose a detail level:10091010| Detail level | Best for |1011| ------------ | --------------------------------------------------------------------------------------------------------------------------- |1012| `low` | Coarse image understanding. Resizing and token use depend on the model; `low` does not always use fewer tokens than `high`. |1013| `high` | Standard high-fidelity image understanding when precise original-image coordinates are not required. |1014| `original` | Large, dense, spatially sensitive, or computer-use images, when supported by the model. |1015| `auto` | Use the model's default sizing behavior, shown in the model sizing table. |10161017For tasks that require fine visual detail or precise coordinates, such as optical character recognition (OCR), small-object detection, or computer use, use `"detail": "original"` when supported. Original detail can still resize images to meet the model's pixel-dimension limit or resizing patch budget, but not to meet the separate 30,000-patch rejection limit. For coordinate-sensitive tasks, resize images to fit those limits before sending them and map returned coordinates back to the original image. See the [Computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for coordinate handling.10181019### Model sizing behavior10201021The following table summarizes sizing behavior for general-purpose vision models. Other models and specialized variants can use different limits. All resizing preserves aspect ratio without enlarging smaller images.10221023<table>1024 <tr>1025 <th>Model family</th>1026 <th>Supported detail levels</th>1027 <th>Patch and resizing behavior</th>1028 </tr>1029 <tr>1030 <td>1031 `gpt-6-astra`1032 </td>1033 <td>1034 `low`, `high`, `original`,1035 `auto`1036 </td>1037 <td>1038 `low` fits within 512 × 512 pixels. `high` allows up1039 to 2,500 patches and a 65,535-pixel maximum dimension. Both limits apply. 1040 `original` preserves the image's dimensions, except that images1041 larger than 65,535 pixels on either side are scaled down to fit that1042 limit. If the resulting image requires more than 1043 [30,000 patches](#image-input-requirements), the API rejects1044 the request; the image is not resized to fit the patch limit. 1045 `auto` uses the same sizing behavior as `original`.1046 </td>1047 </tr>1048 <tr>1049 <td>1050 `gpt-5.6-sol`, `gpt-5.6-terra`, 1051 `gpt-5.6-luna`1052 </td>1053 <td>1054 `low`, `high`, `original`,1055 `auto`1056 </td>1057 <td>1058 `low` fits within 512 × 512 pixels. `high` fits1059 within 2048 × 2048 pixels and 2,500 patches. `original` 1060 preserves the image's dimensions, except that images larger than 65,5351061 pixels on either side are scaled down to fit that limit. If the resulting1062 image requires more than 1063 [30,000 patches](#image-input-requirements), the API rejects1064 the request; the image is not resized to fit the patch limit. 1065 `auto` uses the same sizing behavior as `original`.1066 </td>1067 </tr>1068 <tr>1069 <td>1070 `gpt-5.5`1071 </td>1072 <td>1073 `low`, `high`, `original`,1074 `auto`1075 </td>1076 <td>1077 `low` fits within 512 × 512 pixels. `high` allows up1078 to 2,500 patches and a 2048-pixel maximum dimension. `original` 1079 allows up to 10,000 patches and a 6000-pixel maximum dimension. Both1080 limits apply. `auto` uses the same sizing behavior as 1081 `original`.1082 </td>1083 </tr>1084 <tr>1085 <td>1086 `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`1087 </td>1088 <td>1089 `low`, `high`, `original`,1090 `auto`1091 </td>1092 <td>1093 `low` uses a 2048-pixel maximum dimension and a 6,144-patch1094 budget, so it can use more tokens than `high`. 1095 `high` allows up to 2,500 patches and a 2048-pixel maximum1096 dimension. `original` allows up to 10,000 patches and a1097 6000-pixel maximum dimension. Both limits apply. `auto` uses1098 the same sizing behavior as `high`.1099 </td>1100 </tr>1101 <tr>1102 <td>1103 `gpt-5.2`, `gpt-4.1-mini`1104 </td>1105 <td>1106 `low`, `high`, `auto`1107 </td>1108 <td>1109 These detail levels use the same sizing limits: a 2048-pixel maximum1110 dimension and a 6,144-patch budget. `original` is not1111 supported.1112 </td>1113 </tr>1114 <tr>1115 <td>1116 `gpt-5.1`, `gpt-4.1`, `gpt-4o`,1117 `gpt-4o-mini`1118 </td>1119 <td>1120 `low`, `high`, `auto`1121 </td>1122 <td>1123 `low` uses a fixed token count. `high` and 1124 `auto` use the 1125 [tile-based sizing rules](#tile-based-image-tokenization).1126 </td>1127 </tr>1128</table>11291130## Calculating costs11311132Vision models convert image inputs into billable input tokens. The [image input cost calculator](https://developers.openai.com/api/docs/guides/image-cost-calculator) and patch/tile rules in this section cover vision-model inputs, not GPT Image generation or editing. See [GPT Image model inputs](#gpt-image-model-inputs) for that separate pricing.11331134Image tokens also count toward your [tokens per minute (TPM) limits](https://developers.openai.com/api/docs/guides/rate-limits). The calculator estimates one image at standard input rates; it does not include the rest of your prompt or model output.11351136### Image input cost calculator11371138Use the [image input cost calculator](https://developers.openai.com/api/docs/guides/image-cost-calculator) to estimate input tokens and cost for one image by model, image size, and detail level.11391140### Patch-based image tokenization11411142Some models tokenize images by covering them with 32px x 32px patches. Many model and detail-level combinations define a resizing patch budget. First, the API fits the image within the selected detail level's pixel-dimension limit, preserving aspect ratio and rounding to integer pixels without enlarging smaller images. The token cost is then determined as follows:11431144A. Compute how many 32px x 32px patches are needed to cover the image after applying the pixel-dimension limit. A patch may extend beyond the image boundary.11451146```1147patch_count = ceil(width/32)×ceil(height/32)1148```11491150B. When the selected model and detail level specify a resizing patch budget, scale the image down proportionally if it exceeds that budget. Otherwise, skip this step. Adjust the scale to stay within budget after converting to integer pixel dimensions and computing patch coverage. Keep full precision until calculating the final dimensions.11511152```1153shrink_factor = sqrt((32^2 * patch_budget) / (width * height))1154adjusted_shrink_factor = shrink_factor * min(1155 floor(width * shrink_factor / 32) / (width * shrink_factor / 32),1156 floor(height * shrink_factor / 32) / (height * shrink_factor / 32)1157)1158```11591160C. If step B resized the image, round down the final scaled width and height to integer pixels. Compute the patches needed to cover the resulting image. This is the image-token count before applying the model multiplier. When a patch budget applies, this count stays within that budget.11611162```1163resized_patch_count = ceil(resized_width/32)×ceil(resized_height/32)1164```11651166If this count exceeds 30,000 patches, the API rejects the request. Check this limit before applying the token multiplier.11671168D. Multiply the patch count by the model's multiplier and round up to get the billable image input tokens. Apply the model's input price to those tokens once; the multiplier does not apply to other prompt tokens or to the price again.11691170| Model | Multiplier |1171| -------------------------------------- | ---------- |1172| `gpt-6-astra` | 1.2 |1173| `gpt-5.6-sol` | 1.2 |1174| `gpt-5.6-terra` | 1.2 |1175| `gpt-5.6-luna` | 1.2 |1176| `gpt-5.5` | 1.2 |1177| `gpt-5.4` | 1.2 |1178| `gpt-5.4-mini` | 1.2 |1179| `gpt-5.4-nano` | 1.2 |1180| `gpt-5.2` | 1.2 |1181| `gpt-5-mini`\* | 1.2 |1182| `gpt-5-nano`\* | 1.5 |1183| `gpt-4.1-mini` | 1.62 |1184| `gpt-4.1-nano`\* (2025-04-14 snapshot) | 2.46 |1185| `o4-mini`\* | 1.72 |11861187_For `gpt-4.1-mini`, this applies to the 2025-04-14 snapshot._11881189\* Deprecated and scheduled for shutdown. See the [deprecation schedule](https://developers.openai.com/api/docs/deprecations) for dates and replacements. These models aren't included in the calculator or the model sizing table above.11901191**Image token calculation examples for `gpt-6-astra` with `detail: high`**11921193This combination uses a 65,535-pixel maximum dimension, a 2,500-patch budget, and a 1.2× multiplier.11941195- A 1024 × 1024 image needs `32 × 32 = 1024` patches. No resizing is needed. The billable image input is `ceil(1024 × 1.2) = 1229` tokens.1196- A 2048 × 2048 image initially needs `64 × 64 = 4096` patches. The patch budget reduces it to 1600 × 1600 pixels, or `50 × 50 = 2500` patches. The estimate is `ceil(2500 × 1.2) = 3000` tokens.1197- A 4096 × 512 image stays at its original size: `128 × 16 = 2048` patches and `ceil(2048 × 1.2) = 2458` tokens.11981199Floating-point rounding in billing can make the final count differ from the estimate by one token.12001201### Tile-based image tokenization12021203<a id="gpt-4o-gpt-41-gpt-4o-mini-cua-and-o-series-except-o4-mini"></a>12041205The models in this table use a base token count plus tokens for image tiles:12061207| Model | Base tokens | Tile tokens |1208| -------------------------- | ----------- | ----------- |1209| `gpt-5.1` | 70 | 140 |1210| `gpt-5`\* | 70 | 140 |1211| `gpt-4o`, `gpt-4.1` | 85 | 170 |1212| `gpt-4o-mini` | 2833 | 5667 |1213| `o1`\*, `o1-pro`\*, `o3`\* | 75 | 150 |12141215\* Deprecated and scheduled for shutdown. See the [deprecation schedule](https://developers.openai.com/api/docs/deprecations) for dates and replacements. These models aren't included in the calculator or the model sizing table above.12161217With `"detail": "low"`, an image costs only the model's base tokens, regardless of dimensions. With `"detail": "high"` or `"detail": "auto"`:12181219- Scale down to fit in a 2048px x 2048px square, maintaining aspect ratio. Smaller images are not enlarged.1220- If the shortest side exceeds 768px, scale it down to 768px and round down the other dimension.1221- Count the 512px squares needed to cover the image. Each square uses the model's tile tokens.1222- Add the model's base tokens to the tile tokens.12231224### GPT Image model inputs12251226GPT Image models use separate image-token pricing for generation and editing. The vision calculator does not estimate their input or output costs. For current rates, see [image generation pricing](https://developers.openai.com/api/docs/pricing#image-generation); for generation and editing workflows, see the [Image generation guide](https://developers.openai.com/api/docs/guides/image-generation).12271228#### GPT Image 112291230The following input-token rules apply to `gpt-image-1`. Use tile-based image sizing, but scale the shortest side down to 512px instead of 768px. Token use depends on the image dimensions and the `input_fidelity` parameter in the [Images API](https://developers.openai.com/api/reference/resources/images/methods/edit).12311232When input fidelity is set to low, the base cost is 65 image tokens, and each tile costs 129 image tokens.1233When using high input fidelity, we add a set number of tokens based on the image's aspect ratio in addition to the image tokens described above.12341235- If your image is square, we add 4160 extra input image tokens.1236- If it is closer to portrait or landscape, we add 6240 extra tokens.12371238To see pricing for image input tokens, refer to the [image pricing section](https://developers.openai.com/api/docs/pricing#multimodal-image-pricing).12391240## Limitations12411242Vision models can make mistakes. Account for these limitations when designing your application:12431244- **Medical images**: The model is not suitable for interpreting specialized medical images like CT scans and shouldn't be used for medical advice.1245- **Non-English**: The model may not perform optimally when handling images with text of non-Latin alphabets, such as Japanese or Korean.1246- **Small text**: Enlarge text within the image to improve readability. When available, using `"detail": "original"` can also help performance.1247- **Rotation**: The model may misinterpret rotated or upside-down text and images.1248- **Visual elements**: The model may struggle to understand graphs or text where colors or styles—like solid, dashed, or dotted lines—vary.1249- **Spatial reasoning**: The model struggles with tasks requiring precise spatial localization, such as identifying chess positions.1250- **Accuracy**: The model may generate incorrect descriptions or captions in certain scenarios.1251- **Image shape**: The model struggles with panoramic and fisheye images.1252- **Metadata and resizing**: The model doesn't process original file names or metadata. Images may be resized before analysis, including with `original` detail. See [Model sizing behavior](#model-sizing-behavior) for the limits that apply to each model.1253- **Counting**: The model may give approximate counts for objects in images.1254- **CAPTCHAs**: For safety reasons, our system blocks the submission of CAPTCHAs.