# Chat completion

> Generate text from a conversation of messages, with multimodal input and a selectable intelligence level. OpenAI-style response envelope.

Source: https://docs.generalinput.com/api/platform/chat-completion



<Endpoint method="POST" path="/v1/platform/chat-completion" />

<Access scope="platform:use" />

The model behind the platform's own agents, exposed as a completion call. You pick a capability level rather than a model id.

## Body [#body]

| Field               | Type      | Required | Notes                                                                                                                                                |
| ------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `intelligenceLevel` | string    | yes      | `low` (fast, cheap), `medium` (balanced), or `high` (complex reasoning).                                                                             |
| `messages`          | object\[] | yes      | System, user, and assistant messages. See formats below.                                                                                             |
| `max_tokens`        | number    | no       | Leave unset. The model reasons before it writes, and a cap is spent on reasoning first, returning empty content. Bound length in the prompt instead. |

Message formats:

* System: `{ "role": "system", "content": "…" }`
* User, text: `{ "role": "user", "content": "…" }`
* User, multimodal: `{ "role": "user", "content": [ { "type": "text", "text": "…" }, { "type": "image", "image": "<url or base64>", "mimeType": "image/png" }, { "type": "file", "data": "<url or base64>", "mimeType": "application/pdf" } ] }`
* Assistant: `{ "role": "assistant", "content": "…" }`

`mimeType` is optional on images and required on files.

## Response [#response]

A standard chat completion object. The generated text is at `choices[0].message.content`, and each choice also carries an `index`; `usage` carries `prompt_tokens`, `completion_tokens`, and `total_tokens`.

```json
{
  "choices": [
    {
      "message": { "role": "assistant", "content": "…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 48,
    "total_tokens": 168
  }
}
```

## Choosing a level [#choosing-a-level]

| Level    | Use when                                                                 |
| -------- | ------------------------------------------------------------------------ |
| `low`    | Mechanical work: pattern matching, labeling, extracting structured data. |
| `medium` | Understanding and rephrasing: read, compress, or reshape information.    |
| `high`   | Reasoning, creativity, expert knowledge: synthesize, argue, plan, write. |

## Example [#example]

```sh
curl -s -X POST https://cloud.generalinput.com/v1/platform/chat-completion \
  -H "Authorization: Bearer $GI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intelligenceLevel":"medium","messages":[{"role":"system","content":"Answer in one sentence."},{"role":"user","content":"What does a vault do?"}]}' \
  | jq -r '.choices[0].message.content'
```