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

# Analyze images

> Analyze single or multiple images with Palmyra Vision. Ask questions about images, generate captions, and compare images using the vision endpoint.

<Warning>
  **Deprecation notice**: The following models are deprecated and will be removed on **July 13, 2026**: `palmyra-x-003-instruct`, `palmyra-vision`, `palmyra-med`, `palmyra-fin`, and `palmyra-creative`.

  **Migration path**: Use [`palmyra-x5`](/home/models#palmyra-x5) as the replacement for all deprecated models. Palmyra X5 supports a 1M-token context window and covers general-purpose, financial, medical, and creative use cases. For vision workloads, use [chat with images](/home/chat-with-images) with Palmyra X5 instead of `palmyra-vision`. See the [deprecation policy](/home/models#deprecation-policy) for more information.
</Warning>

With the `vision` endpoint, you can analyze single or multiple images with a prompt. [Palmyra Vision](/home/models#palmyra-vision) allows you to ask questions about an image, generate captions, compare images, and more.

<Note>
  You need an API key to access the Writer API. Get an API key by following the steps in the [API quickstart](/home/quickstart).

  We recommend setting the API key as an environment variable in a `.env` file with the name `WRITER_API_KEY`.
</Note>

## Vision endpoint

**Endpoint:** `POST /v1/vision`

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    'https://api.writer.com/v1/vision' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $WRITER_API_KEY" \
    --data-raw '{
      "model": "palmyra-vision",
      "prompt": "What is the difference between the image {{image_1}} and the image {{image_2}}?",
      "variables": [
        {"name": "image_1", "file_id": "<FILE_ID>"},
        {"name": "image_2", "file_id": "<FILE_ID_2>"}
      ]
    }'
  ```

  ```python Python theme={null}
  from writerai import Writer

  # Initialize the Writer client. If you don't pass the `apiKey` parameter,
  # the client looks for the `WRITER_API_KEY` environment variable.
  client = Writer()

  response = client.vision.analyze(
    model="palmyra-vision",
    prompt="What is the difference between the image {{image_1}} and the image {{image_2}}?",
    variables=[{"name": "image_1", "file_id": "<FILE_ID>"}, {"name": "image_2", "file_id": "<FILE_ID_2>"}]
  )

  print(response.data)
  ```

  ```javascript JavaScript theme={null}
  import { Writer } from "writer-sdk";

  // Initialize the Writer client. If you don't pass the `apiKey` parameter,
  // the client looks for the `WRITER_API_KEY` environment variable.
  const client = new Writer();

  const response = await client.vision.analyze({
    model: "palmyra-vision",
    prompt: "What is the difference between the image {{image_1}} and the image {{image_2}}?",
    variables: [{ name: "image_1", file_id: "<FILE_ID>" }, { name: "image_2", file_id: "<FILE_ID_2>" }]
  });

  console.log(response.data);
  ```
</CodeGroup>

### Request body

The request body is a JSON object with the following fields:

| Parameter             | Type   | Description                                                                                                                                                                                                                          |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `model`               | string | The model to use for the analysis. Must be `palmyra-vision`.                                                                                                                                                                         |
| `prompt`              | string | The prompt to use for the analysis. The prompt must include the names of the images you're analyzing, referencing them as `{{name}}`. For example: `What is the difference between the image {{image_1}} and the image {{image_2}}?` |
| `variables`           | array  | An array of image variables with a `name` and `file_id`.                                                                                                                                                                             |
| `variables[].name`    | string | The name of the image. You must use the same name in the prompt, referencing it as `{{name}}`.                                                                                                                                       |
| `variables[].file_id` | string | The File ID of the uploaded image. The maximum allowed file size is 7 MB. You must upload the image to Writer before passing it to the Vision endpoint. Learn how to [upload images below](#upload-images).                          |

### Response format

The response is a JSON object with a `data` field that contains the analysis results as a string.

```json theme={null}
{
    "data": "The analysis results"
}
```

## Example: Extract text from an image

This example shows how to extract text from an image using the `vision` endpoint.

### Upload an image

Before you can analyze an image, you need to upload it to Writer.

The following code samples demonstrate how to upload an image and print the File ID. You need the File ID to pass to the Vision endpoint.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.writer.com/v1/files' \
    -H 'Content-Type: image/jpeg' \
    -H 'Content-Disposition: attachment; filename=<FILE_NAME>' \
    -H "Authorization: Bearer $WRITER_API_KEY" \
    --data-binary "@<FILE_PATH>"

  # Example:
  #   <FILE_NAME> = handwriting.jpg
  #   <FILE_PATH> = /path/to/handwriting.jpg
  ```

  ```python Python theme={null}
  from pathlib import Path
  from writerai import Writer

  # Initialize the Writer client. If you don't pass the `api_key` parameter,
  # the client looks for the `WRITER_API_KEY` environment variable.
  client = Writer()

  file_ = client.files.upload(
    content=Path("<FILE_PATH>"),  # Replace with your file path, for example: /path/to/handwriting.jpg
    content_disposition="attachment; filename=<FILE_NAME>",  # Replace with your file name, for example: handwriting.jpg
    content_type="image/jpeg"
  )

  print(file_.id)
  ```

  ```javascript JavaScript theme={null}
  import fs from 'fs';
  import { Writer } from "writer-sdk";

  // Initialize the Writer client. If you don't pass the `api_key` parameter,
  // the client looks for the `WRITER_API_KEY` environment variable.
  const client = new Writer();

  const file = await client.files.upload({
    content: fs.createReadStream("<FILE_PATH>"),  // Replace with your file path, for example: /path/to/handwriting.jpg
    "Content-Disposition": "attachment; filename=<FILE_NAME>",  // Replace with your file name, for example: handwriting.jpg
    "Content-Type": "image/jpeg"
  });

  console.log(file.id)
  ```
</CodeGroup>

Learn more about [uploading and managing files](/home/files).

### Generate a caption with the Vision endpoint

Once you have the File IDs for any images you want to analyze, you can pass them to the Vision endpoint along with a prompt.

The prompt must include the names of the images you're analyzing, referencing them as `{{name}}`, where `name` is the name you provided in the `variables` array. For example: `Extract the text from the image {{name}}.` If you include files in the `variables` array that you don't include in the prompt, the API returns an error.

The following code sample shows the API call to extract text from an image.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    'https://api.writer.com/v1/vision' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $WRITER_API_KEY" \
    --data '{
      "model": "palmyra-vision",
      "prompt": "Extract the text from the image {{handwriting}}.",
      "variables": [{"name": "handwriting", "file_id": "<FILE_ID>"}]
    }'
  ```

  ```python Python theme={null}
  from writerai import Writer

  client = Writer()

  response = client.vision.analyze(
    model="palmyra-vision",
    prompt="Extract the text from the image {{handwriting}}.",
    variables=[{"name": "handwriting", "file_id": "<FILE_ID>"}]
  )

  print(response.data)
  ```

  ```javascript JavaScript theme={null}
  import { Writer } from "writer-sdk";

  const client = new Writer();

  const response = await client.vision.analyze({
    model: "palmyra-vision",
    prompt: "Extract the text from the image {{handwriting}}.",
    variables: [{ name: "handwriting", file_id: "<FILE_ID>" }]
  });

  console.log(response.data);
  ```
</CodeGroup>

## Next steps

* Learn how to analyze images during a chat completion with the [Vision tool](/home/vision-tool).