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

# LLM Chat (Native)

> Send chat-style messages to any of the 12 LLMs through a single AdSkull-native endpoint.

`POST /v1/llm/chat` is the simplest way to call any AdSkull LLM. The shape is
stable across all models — switching from `claude-opus-4.7` to `gemini-3-pro` is a one-line change.

## Endpoints

| Method | Endpoint         | Purpose                                                |
| ------ | ---------------- | ------------------------------------------------------ |
| `POST` | `/v1/llm/chat`   | Send messages, get a completion (sync or SSE stream).  |
| `GET`  | `/v1/llm/models` | List all available LLM models + per-token pricing.     |
| `GET`  | `/v1/llm/usage`  | List your recent LLM calls (filter by time, paginate). |

## Parameters

| Field             | Type                | Required | Notes                                                                                                                                            |
| ----------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `model`           | string              | Yes      | An AdSkull model ID, e.g. `claude-opus-4.7`. Aliases like `claude-opus-4-7` also work.                                                           |
| `messages`        | object\[]           | Yes      | One or more `{role, content}` turns. `role` is `system`, `user`, `assistant`, or `tool`. `content` may be a string or a typed-block array.       |
| `max_tokens`      | integer             | No       | Cap on output tokens. Defaults to the model's max.                                                                                               |
| `temperature`     | number              | No       | 0.0 – 2.0.                                                                                                                                       |
| `top_p`           | number              | No       | Nucleus sampling.                                                                                                                                |
| `stop`            | string \| string\[] | No       | Stop sequences.                                                                                                                                  |
| `tools`           | object\[]           | No       | Tool definitions (OpenAI-style schema).                                                                                                          |
| `tool_choice`     | string \| object    | No       | Tool-selection hint.                                                                                                                             |
| `response_format` | object              | No       | e.g. `{"type": "json_object"}` for JSON-mode-capable models.                                                                                     |
| `attachments`     | object\[]           | No       | Convenience array of `{type, url}` entries appended to the last user message. Use `image`, `audio`, `video`, or `file`. URLs are SSRF-validated. |
| `stream`          | boolean             | No       | If `true`, returns Server-Sent Events.                                                                                                           |

<Note>
  `Idempotency-Key` is **strongly recommended** on every non-streaming call so
  retries never double-bill.
</Note>

## Example: text

```bash theme={"theme":"github-dark"}
curl https://api.adskull.io/v1/llm/chat \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-001" \
  -d '{
    "model": "claude-opus-4.7",
    "messages": [
      {"role": "user", "content": "Write a tagline for an iced coffee brand."}
    ],
    "max_tokens": 200
  }'
```

Response:

```json theme={"theme":"github-dark"}
{
  "id": "llm_01J7Y3...",
  "object": "chat.completion",
  "model": "claude-opus-4.7",
  "created": 1730000000,
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Cold takes. Hot ideas.", "tool_calls": null },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 9,
    "cached_tokens": 0,
    "millicredits_charged": 47,
    "credits_charged": 0.047
  }
}
```

## Example: image input

```bash theme={"theme":"github-dark"}
curl https://api.adskull.io/v1/llm/chat \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro",
    "messages": [
      {"role": "user", "content": "What product is in this image?"}
    ],
    "attachments": [
      {"type": "image", "url": "https://example.com/can.jpg"}
    ]
  }'
```

## Example: streaming

Set `"stream": true` and read SSE.

```bash theme={"theme":"github-dark"}
curl -N https://api.adskull.io/v1/llm/chat \
  -H "Authorization: Bearer $ADSKULL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "claude-opus-4.7", "stream": true, "messages": [{"role":"user","content":"hi"}] }'
```

Chunks look like:

```
data: {"type":"start","id":"llm_...","model":"claude-opus-4.7"}

data: {"type":"delta","id":"llm_...","model":"claude-opus-4.7","delta":{"content":"Hi"}}

data: {"type":"done","id":"llm_...","model":"claude-opus-4.7","finish_reason":"stop","usage":{"input_tokens":12,"output_tokens":5,"cached_tokens":0,"millicredits_charged":34,"credits_charged":0.034}}

data: [DONE]
```

## Listing usage

```bash theme={"theme":"github-dark"}
curl https://api.adskull.io/v1/llm/usage?limit=20 \
  -H "Authorization: Bearer $ADSKULL_API_KEY"
```

Returns the last 20 LLM calls (model, endpoint, tokens, millicredits charged,
latency, error\_code if any). Use `cursor` to paginate.