# Chat Completions (OpenAI-compatible)

> POST /v1/chat/completions: the OpenAI Chat Completions API, served by any model you have connected, with tools, images and streaming.

Product: AI Cost Optimizer Gateway (ACOG). Web version: https://tessarac.com/docs/acog/api/chat-completions. Last updated: 2026-10-16.

```http
POST https://gateway.acog.tessarac.com/v1/chat/completions
```

The OpenAI [Chat Completions API](https://platform.openai.com/docs/api-reference/chat). Send exactly what you would send to OpenAI; ACOG routes by `model` to whichever of your connections declares it, translating to and from the Anthropic and Gemini APIs when the model is a Claude or Gemini model.

## Example

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.acog.tessarac.com/v1",
    api_key=os.environ["ACOG_API_KEY"],
)

completion = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[
        {"role": "system", "content": "You are terse."},
        {"role": "user", "content": "Name three prime numbers."},
    ],
)
print(completion.choices[0].message.content)
```

```bash
curl -s https://gateway.acog.tessarac.com/v1/chat/completions \
  -H "Authorization: Bearer $ACOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.5-flash", "messages": [{"role": "user", "content": "Name three prime numbers."}]}'
```

## What is supported

| Feature | Supported |
|---|---|
| System, user, assistant and tool messages | Yes |
| Tools and function calling, tool results | Yes |
| Images in user messages (`image_url`, URL or base64) | Yes. For Bedrock and Vertex, ACOG fetches image URLs and sends them inline (up to 5 MB, 10-second fetch). A failed fetch is a `400`, never a silent drop. |
| Streaming (`stream: true`) | Yes. See [Streaming](https://tessarac.com/docs/acog/api/streaming.md). |
| `model: "auto"` | Yes. See [Auto mode](https://tessarac.com/docs/acog/optimize/auto-mode.md). |
| `<model>:batch` | Run at batch prices. See [Batches](https://tessarac.com/docs/acog/api/batches.md). |
| Audio output | Forwarded to OpenAI-compatible connections; never cached |

## Translation to other providers

When the model is served by a connection that speaks a different API (Claude on Anthropic, Bedrock or Vertex; Gemini on Vertex), ACOG translates the request and the response, including streamed responses.

Translation is strict by default. A field that has no faithful equivalent in the target API is refused with `422 translation_unsupported` rather than silently dropped, so you never get an answer to a different question than the one you asked. An admin can list fields a connection may drop instead.

Translated requests are not stored in the response cache, because the stored reply would be in the target's format.

## The response

The response is an OpenAI chat completion object. `model` names the model that answered. The header `x-acog-resolved-model` carries it too, which is useful when you sent `auto`.

ACOG adds a few response headers of its own, for example `x-acog-cache: hit` when the reply came from a cache. See [Response headers](https://tessarac.com/docs/acog/reference/response-headers.md).

## Errors

Errors use the envelope `{"error": {"type": "…", "message": "…"}}`. An error your provider returned is passed through unchanged. See [Errors](https://tessarac.com/docs/acog/reference/errors.md).