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

# Images endpoint

> Search for images using AI-powered query understanding

The images endpoint allows you to search for images using AI to understand and refine your query based on conversation context.

## Endpoint

<CodeGroup>
  ```bash POST /api/images theme={null}
  http://localhost:3000/api/images
  ```
</CodeGroup>

<Note>Replace `localhost:3000` with your Perplexica instance URL if running on a different host or port.</Note>

## Request body

<ParamField body="query" type="string" required>
  The image search query.
</ParamField>

<ParamField body="chatModel" type="object" required>
  Defines the chat model to be used for understanding and refining the query. Get available providers and models from the `/api/providers` endpoint.

  <Expandable title="properties">
    <ParamField body="providerId" type="string" required>
      The UUID of the provider. You can get this from the `/api/providers` endpoint response.
    </ParamField>

    <ParamField body="key" type="string" required>
      The model key/identifier (e.g., `gpt-4o-mini`, `llama3.1:latest`). Use the `key` value from the provider's `chatModels` array.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="chatHistory" type="array">
  An array of message pairs representing the conversation history. Each pair consists of a role (either `human` or `assistant`) and the message content.

  Example:

  ```json theme={null}
  [
    ["human", "Show me photos of cats"],
    ["assistant", "Here are some images of cats..."]
  ]
  ```
</ParamField>

## Response

<ResponseField name="images" type="array">
  A list of image search results. The structure of each image object depends on the search provider's response format.
</ResponseField>

## Request example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:3000/api/images \
    -H "Content-Type: application/json" \
    -d '{
      "query": "golden retriever puppies",
      "chatModel": {
        "providerId": "550e8400-e29b-41d4-a716-446655440000",
        "key": "gpt-4o-mini"
      },
      "chatHistory": []
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:3000/api/images', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: 'golden retriever puppies',
      chatModel: {
        providerId: '550e8400-e29b-41d4-a716-446655440000',
        key: 'gpt-4o-mini'
      },
      chatHistory: []
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'http://localhost:3000/api/images',
      json={
          'query': 'golden retriever puppies',
          'chatModel': {
              'providerId': '550e8400-e29b-41d4-a716-446655440000',
              'key': 'gpt-4o-mini'
          },
          'chatHistory': []
      }
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

## Response example

```json theme={null}
{
  "images": [
    {
      "url": "https://example.com/image1.jpg",
      "title": "Golden Retriever Puppy",
      "thumbnail": "https://example.com/thumb1.jpg"
    },
    {
      "url": "https://example.com/image2.jpg",
      "title": "Cute Golden Retriever Puppies",
      "thumbnail": "https://example.com/thumb2.jpg"
    }
  ]
}
```

<Note>
  The AI model processes your query and conversation history to refine the search and return more relevant results.
</Note>

## Error responses

<ResponseField name="500" type="Internal Server Error">
  Returned if an error occurs while searching images.
</ResponseField>