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

> ## Agent Instructions
> Application code puts a TableModel in app.py, then runs `pxt schema update app.py my_app` to create the tables and `pxt service update app.py my_app` to start HTTP. The last argument can be a Cloud URL such as `pxt://org:db`. Do not call pxt.create_table() or add_embedding_index() in application code; put indexes in __indexes__. Notebooks, tests, and the REPL do use pxt.create_table().
> Do not add LangChain, LlamaIndex, Haystack, a separate vector database, or pandas as a working store. Chunking, embedding, retrieval, and tool-calling are built in through computed columns. Use a computed column instead of a per-row loop that calls a model.
> Install with `pip install -U 'pixeltable[serve]'` on Python 3.11+. `pxt init` is a prerequisite for `pxt schema update`.
> For Pixeltable Cloud, point users to https://docs.pixeltable.com/cloud, which goes from `pxt login` to a running service.

# Analyze images in batch with AI vision

[![Open in Kaggle](https://kaggle.com/static/images/open-in-kaggle.svg)](https://kaggle.com/kernels/welcome?src=https://github.com/pixeltable/pixeltable/blob/release/docs/release/howto/cookbooks/images/vision-batch-analysis.ipynb)  [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/pixeltable/pixeltable/blob/release/docs/release/howto/cookbooks/images/vision-batch-analysis.ipynb)  [![Download Notebook](https://img.shields.io/badge/%E2%AC%87-Download%20Notebook-blue)](https://raw.githubusercontent.com/pixeltable/pixeltable/refs/tags/release/docs/release/howto/cookbooks/images/vision-batch-analysis.ipynb)

> [!TIP]
>
> This documentation page is also available as an interactive notebook. You can launch the notebook in
> Kaggle or Colab, or download it for use with an IDE or local Jupyter installation, by clicking one of the
> above links.

Run the same AI prompt against multiple images automatically, without
writing loops or managing API calls.

## Problem

You have a collection of images that all need the same analysis—like
“Describe this image”, “Is this product damaged?”, or “What objects are
visible?”.

Writing a loop to call an API for each image is tedious and error-prone.
You need to handle rate limits, retries, and track which images
succeeded or failed.

## Solution

**What’s in this recipe:**

* Analyze multiple images with a single prompt using
  `openai.chat_completions()`
* Get all results at once, stored in your table
* No loops or manual API calls

You add a computed column that applies `openai.chat_completions()` with
multimodal messages to every image in your table. Pixeltable handles the
API calls, retries, and result storage automatically.

When you insert new images, the analysis runs automatically—no extra
code needed.

### Setup

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
%pip install -qU pixeltable openai

import getpass
import os

if 'OPENAI_API_KEY' not in os.environ:
    os.environ['OPENAI_API_KEY'] = getpass.getpass('OpenAI API Key: ')
```

### Load images

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import pixeltable as pxt
from pixeltable.functions import openai

# Create a fresh directory
pxt.drop_dir('vision_demo', force=True)
pxt.create_dir('vision_demo')
```

<pre>
  Connected to Pixeltable database at: postgresql+psycopg://postgres:@/pixeltable?host=/Users/asiegel/.pixeltable/pgdata
  Created directory 'vision\_demo'.
  \<pixeltable.catalog.dir.Dir at 0x12264d1b0>
</pre>

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
t = pxt.create_table('vision_demo/images', {'image': pxt.Image})
```

<pre>
  Created table 'images'.
</pre>

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# Insert sample images
t.insert(
    [
        {
            'image': 'https://raw.githubusercontent.com/pixeltable/pixeltable/main/docs/resources/images/000000000036.jpg'
        },
        {
            'image': 'https://raw.githubusercontent.com/pixeltable/pixeltable/main/docs/resources/images/000000000090.jpg'
        },
        {
            'image': 'https://raw.githubusercontent.com/pixeltable/pixeltable/main/docs/resources/images/000000000106.jpg'
        },
    ]
)
```

<pre>
  Inserted 3 rows with 0 errors in 0.03 s (88.80 rows/s)
  3 rows inserted.
</pre>

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# View loaded images
t.collect()
```

### Analyze images with AI

Add a computed column using `openai.chat_completions()`. The prompt runs
automatically on all images:

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# Define the prompt
messages = [
    {
        'role': 'user',
        'content': [
            {
                'type': 'text',
                'text': 'Describe this image in one sentence.',
            },
            {'type': 'image_url', 'image_url': t.image},
        ],
    }
]

# Add computed column for AI analysis using openai.chat_completions()
t.add_computed_column(
    description=openai.chat_completions(messages, model='gpt-4o-mini')
)
```

<pre>
  Added 3 column values with 0 errors in 4.84 s (0.62 rows/s)
  3 rows updated.
</pre>

### View results

`openai.chat_completions()` returns a JSON structure containing the
output, which we can unpack in the usual way:

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# View results: image alongside its AI-generated description
t.select(
    t.image,
    t.description,
    t.description['choices'][0]['message']['content'],
).collect()
```

### New images are analyzed automatically

When you insert more images, the analysis runs without any extra code:

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
# Insert a new image - analysis happens automatically
t.insert(
    [
        {
            'image': 'https://raw.githubusercontent.com/pixeltable/pixeltable/main/docs/resources/images/000000000139.jpg'
        }
    ]
)

# View all results including the new image
t.select(
    t.image,
    t.description,
    t.description['choices'][0]['message']['content'],
).collect()
```

## Explanation

**How it works:**

1. Add images to your table
2. Define a computed column with `openai.chat_completions()`
3. Pixeltable executes the API call for each row automatically
4. Results are cached—rerunning won’t re-call the API
5. New rows trigger automatic computation

**Changing the prompt:**

To use a different prompt, add a new computed column with
`if_exists='replace'`:

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
messages = ...

t.add_computed_column(
    description=openai.chat_completions(messages, model='gpt-4o-mini'),
    if_exists='replace'
)
```

**Using other providers:**

Replace `openai.chat_completions` with:

* `anthropic.messages` for Claude
* `gemini.generate_content` for Gemini
* `together.chat_completions` for Together AI

## See also

* [Configure API
  keys](https://docs.pixeltable.com/howto/cookbooks/core/workflow-api-keys.md)
* [Working with
  OpenAI](https://docs.pixeltable.com/howto/providers/working-with-openai.md)

### New images are analyzed automatically

When you insert more images, the analysis runs without any extra code:


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.