# Chat Completions

Send messages to a Genesis model that supports Chat Completions and return generated content.

```text
POST https://token.moi.matrixorigin.cn/v1/chat/completions
```

## Before you call

Prepare credentials with Genesis access and obtain a model ID from [List models](../models.md). Confirm that the selected model supports Chat Completions.

## Request body

Replace `$GENESIS_ACCESS_TOKEN` with an access token or service-account API key, and `$MODEL_ID` with the model ID to call.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl -X POST \
  "https://token.moi.matrixorigin.cn/v1/chat/completions" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "messages": [{"role": "user", "content": "Explain the purpose of a database transaction in one sentence."}],
    "max_tokens": 128
  }'
```

:::::
:::::{tab-item} Parameter description

::::{tab-set}
:::{tab-item} Parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | Yes | Chat Completions model ID to call. |
| `messages` | array of object | Yes | Ordered list of messages to submit. |
| `max_tokens` | integer | No | Maximum output tokens for this generation; use only values supported by the selected model. |
| `temperature` | number | No | Sampling temperature; set only when the selected model supports it. |
| `stream` | boolean | No | Set to `true` to request streaming output; see Streaming response. |

:::
:::{tab-item} Message item

The following table expands each item in the example `messages` array.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | string | Yes | Message role. |
| `content` | string | Yes | Text content of the message. |

:::
::::

:::::
::::::
:::::::

## Successful response

The service returns a model-generated message.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "id": "<COMPLETION_ID>",
  "object": "chat.completion",
  "model": "<MODEL_ID>",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "A transaction executes a group of operations as a whole to preserve data consistency."},
      "finish_reason": "stop"
    }
  ]
}
```

:::::
:::::{tab-item} Field description

::::{tab-set}
:::{tab-item} Common fields

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Identifier for this Completion. |
| `object` | string | Response object type; the example is `chat.completion`. |
| `model` | string | Model ID that processed the request. |
| `choices` | array of object | List of generated results. |

:::
:::{tab-item} Result item

The following table expands each item in the example `choices` array.

| Field | Type | Description |
| --- | --- | --- |
| `index` | integer | Position of this result in the list. |
| `message` | object | Assistant message. |
| `finish_reason` | string | Reason the current generation ended. |

:::
:::{tab-item} Message object

The following table expands the example `choices[].message` object.

| Field | Type | Description |
| --- | --- | --- |
| `role` | string | Message role. |
| `content` | string | Text generated by the assistant. |

:::
::::

:::::
::::::
:::::::

## Streaming response

Set `stream` to `true` and send `Accept: text/event-stream` to request streaming output. The service returns `text/event-stream`; continue reading incremental content from events until `data: [DONE]` arrives. An error before the stream is established is a JSON error object with the same shape as Error response.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Call example

```bash
curl -N -X POST \
  "https://token.moi.matrixorigin.cn/v1/chat/completions" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{"model":"'"$MODEL_ID"'","messages":[{"role":"user","content":"Explain the purpose of a primary key in one sentence."}],"stream":true}'
```

:::::
:::::{tab-item} Response example

```text
data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":"A primary key"}}]}

data: {"object":"chat.completion.chunk","choices":[{"delta":{"content":" uniquely identifies each row in a table."}}]}

data: [DONE]
```

:::::
:::::{tab-item} Field description

::::{tab-set}
:::{tab-item} Common fields

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Event object type; the example is `chat.completion.chunk`. |
| `choices` | array of object | Incremental results in the current event. |
| `[DONE]` | event marker | Normal completion marker; mark the result complete only after receiving it. |

:::
:::{tab-item} Result item

| Field | Type | Description |
| --- | --- | --- |
| `delta` | object | Incremental object. |

:::
:::{tab-item} Incremental content

| Field | Type | Description |
| --- | --- | --- |
| `content` | string | Append it to the current text when present. |

:::
::::

:::::
::::::
:::::::

## Error response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{"error":{"message":"<human-readable error message>","type":"<error type; may be omitted>","code":"<error code; may be omitted>"}}
```

:::::
:::::{tab-item} Field description

::::{tab-set}
:::{tab-item} Common fields

| Field | Type | Description |
| --- | --- | --- |
| `error` | object | Error object. |

:::
:::{tab-item} Error object

| Field | Type | Description |
| --- | --- | --- |
| `message` | string | Human-readable error message. |
| `type` | string | Error category returned by the model service; it may be omitted. |
| `code` | string or null | Error code returned by the model service; it may be omitted. |

:::
::::

:::::
::::::
:::::::

## Next steps

For streaming reads, see Streaming response above. For other request shapes, see [Responses](responses.md) and [Messages (Anthropic)](anthropic-messages.md).