> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auriko.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vision

> Analyze images alongside text in chat completions

Auriko supports vision through the OpenAI-compatible `image_url` content part. Pass an image URL or a base64 data URL in the `content` array of a user message.

## Prerequisites

* An [Auriko API key](https://auriko.ai/signup?redirectTo=%2Fdashboard%3Ftab%3Dapi-keys)
* Python 3.10+ with the OpenAI SDK (`pip install openai`) or the auriko SDK (`pip install auriko`)
  * OR Node.js 18+ with the OpenAI SDK (`npm install openai`) or `@auriko/sdk` (`npm install @auriko/sdk`)
* A vision-capable model (e.g., `gpt-4o`, `claude-sonnet-4-6`, `gemini-flash-latest`)

## Analyze images from URLs

Pass an image URL as a content part in the user message:

<CodeGroup>
  ```python Python OpenAI theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1",
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{
          "role": "user",
          "content": [
              {"type": "text", "text": "What is in this image?"},
              {"type": "image_url", "image_url": {
                  "url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png"
              }},
          ],
      }],
      max_tokens=300,
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{
          role: "user",
          content: [
              { type: "text", text: "What is in this image?" },
              { type: "image_url", image_url: {
                  url: "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
              } },
          ],
      }],
      max_tokens: 300,
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  import os
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1",
  )

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[
          {
              "role": "user",
              "content": [
                  {"type": "text", "text": "What is in this image?"},
                  {
                      "type": "image_url",
                      "image_url": {
                          "url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png"
                      },
                  },
              ],
          }
      ],
      max_tokens=300,
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [
          {
              role: "user",
              content: [
                  { type: "text", text: "What is in this image?" },
                  {
                      type: "image_url",
                      image_url: {
                          url: "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
                      },
                  },
              ],
          },
      ],
      max_tokens: 300,
  });

  console.log(response.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{
        "role": "user",
        "content": [
          {"type": "text", "text": "What is in this image?"},
          {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png"}}
        ]
      }],
      "max_tokens": 300
    }'
  ```
</CodeGroup>

## Analyze base64-encoded images

For local files or private images, encode the bytes as a data URL:

<CodeGroup>
  ```python Python OpenAI theme={null}
  import base64
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1",
  )

  with open("chart.png", "rb") as f:
      b64 = base64.b64encode(f.read()).decode("utf-8")

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{
          "role": "user",
          "content": [
              {"type": "text", "text": "Summarize the trend in this chart."},
              {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
          ],
      }],
      max_tokens=500,
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";
  import fs from "node:fs";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const b64 = fs.readFileSync("chart.png").toString("base64");

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{
          role: "user",
          content: [
              { type: "text", text: "Summarize the trend in this chart." },
              { type: "image_url", image_url: { url: `data:image/png;base64,${b64}` } },
          ],
      }],
      max_tokens: 500,
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  import base64
  import os
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1",
  )

  with open("chart.png", "rb") as f:
      b64 = base64.b64encode(f.read()).decode("utf-8")

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[
          {
              "role": "user",
              "content": [
                  {"type": "text", "text": "Summarize the trend in this chart."},
                  {
                      "type": "image_url",
                      "image_url": {"url": f"data:image/png;base64,{b64}"},
                  },
              ],
          }
      ],
      max_tokens=500,
  )

  print(response.choices[0].message.content)
  ```

  ```typescript TypeScript Auriko theme={null}
  import fs from "node:fs";
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  const b64 = fs.readFileSync("chart.png").toString("base64");

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [
          {
              role: "user",
              content: [
                  { type: "text", text: "Summarize the trend in this chart." },
                  {
                      type: "image_url",
                      image_url: { url: `data:image/png;base64,${b64}` },
                  },
              ],
          },
      ],
      max_tokens: 500,
  });

  console.log(response.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{
        "role": "user",
        "content": [
          {"type": "text", "text": "What is in this image?"},
          {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"}}
        ]
      }],
      "max_tokens": 300
    }'
  ```
</CodeGroup>

## Send multiple images

Send several images in a single request by adding multiple `image_url` content parts:

<CodeGroup>
  ```python Python OpenAI theme={null}
  messages=[{
      "role": "user",
      "content": [
          {"type": "text", "text": "Compare these two images."},
          {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png"}},
          {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"}},
      ],
  }]
  ```

  ```typescript TypeScript OpenAI theme={null}
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{
          role: "user",
          content: [
              { type: "text", text: "Compare these two images." },
              { type: "image_url", image_url: { url: "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png" } },
              { type: "image_url", image_url: { url: "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" } },
          ],
      }],
      max_tokens: 300,
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  messages=[
      {
          "role": "user",
          "content": [
              {"type": "text", "text": "Compare these two images."},
              {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png"}},
              {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"}},
          ],
      }
  ]
  ```

  ```typescript TypeScript Auriko theme={null}
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{
          role: "user",
          content: [
              { type: "text", text: "Compare these two images." },
              { type: "image_url", image_url: { url: "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png" } },
              { type: "image_url", image_url: { url: "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg" } },
          ],
      }],
      max_tokens: 300,
  });
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{
        "role": "user",
        "content": [
          {"type": "text", "text": "Compare these two images."},
          {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png"}},
          {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"}}
        ]
      }],
      "max_tokens": 300
    }'
  ```
</CodeGroup>

## Control image resolution

You can set `detail` on the `image_url` content part to control how much resolution the model uses:

<CodeGroup>
  ```python Python OpenAI theme={null}
  {
      "type": "image_url",
      "image_url": {
          "url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
          "detail": "low",
      },
  }
  ```

  ```typescript TypeScript OpenAI theme={null}
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{
          role: "user",
          content: [
              { type: "text", text: "Describe this image." },
              {
                  type: "image_url",
                  image_url: {
                      url: "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
                      detail: "low",
                  },
              },
          ],
      }],
      max_tokens: 300,
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  {
      "type": "image_url",
      "image_url": {
          "url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
          "detail": "low",
      },
  }
  ```

  ```typescript TypeScript Auriko theme={null}
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{
          role: "user",
          content: [
              { type: "text", text: "Describe this image." },
              {
                  type: "image_url",
                  image_url: {
                      url: "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png",
                      detail: "low",
                  },
              },
          ],
      }],
      max_tokens: 300,
  });
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{
        "role": "user",
        "content": [
          {"type": "text", "text": "Describe this image."},
          {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png", "detail": "low"}}
        ]
      }],
      "max_tokens": 300
    }'
  ```
</CodeGroup>

| Value  | Behavior                                                |
| ------ | ------------------------------------------------------- |
| `auto` | The model decides based on image size (default)         |
| `low`  | Fixed low-resolution processing, fewer tokens           |
| `high` | High-resolution processing, more tokens for fine detail |

Use `low` for cost-sensitive workloads where fine detail isn't needed. Use `high` when the model needs to read small text or distinguish fine visual features.

## Response shape

Vision responses use the standard `ChatCompletionResponse` shape. The model's analysis appears in `choices[0].message.content` as text.

## Errors

| Situation                                      | HTTP  | SDK error         |
| ---------------------------------------------- | ----- | ----------------- |
| Image too large for the model's context window | `400` | `BadRequestError` |
| Model doesn't support vision                   | `400` | `BadRequestError` |

Some models accept image URLs directly. Others require Auriko to process the image first, which adds these constraints:

| Situation                             | HTTP  | SDK error         |
| ------------------------------------- | ----- | ----------------- |
| Image URL unreachable                 | `400` | `BadRequestError` |
| Total image data exceeds 30 MB        | `400` | `BadRequestError` |
| More than 1,500 images in one request | `400` | `BadRequestError` |
| Image URL isn't HTTPS                 | `400` | `BadRequestError` |
| Unsupported image format              | `400` | `BadRequestError` |

<Note>
  URL resolution behavior varies by model. For consistent results across models, use base64-encoded images.
</Note>

Check [Supported parameters](/contract/supported-parameters) for the accepted `content` part types and see [Error codes](/contract/error-codes) for the full error taxonomy.

## Related

* [Streaming](/guides/streaming) — stream vision responses chunk-by-chunk
* [Tool calling](/guides/tool-calling) — combine vision with function calling
* [Structured output](/guides/structured-output) — extract structured data from images
* [Image generation](/guides/image-generation) — generate images with Gemini models