# Models

OpenAI-compatible chat and responses inference, streaming, and model discovery over /v1.

## Chat completions

`client.chat.completions.create` posts to `/v1/chat/completions`. Required fields are `model` and `messages`; common options include `temperature`, `max_tokens`, `tools`, `tool_choice`, and `response_format`. The scope is `model:invoke`.

```bash
const completion = await client.chat.completions.create({
  model: "claude-opus-4-8",
  messages: [
    { role: "system", content: "You are concise." },
    { role: "user", content: "Name three primary colors." },
  ],
  max_tokens: 256,
});
console.log(completion.choices[0].message.content);
```

## Streaming

Pass `stream: true` and the call resolves to an `AsyncIterable` of chunks (the gateway responds with `text/event-stream`). Read `chunk.choices[0].delta.content` for each token.

```bash
const stream = await client.chat.completions.create({
  model: "claude-opus-4-8",
  messages: [{ role: "user", content: "Write a haiku about the sea." }],
  stream: true,
});
for await (const chunk of stream) {
  const delta = chunk.choices?.[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}
```

## Responses API

`client.responses.create` posts to `/v1/responses` (OpenAI-compatible Responses payload, passthrough). It also supports `stream: true`, returning an `AsyncIterable` of chunks.

```bash
const result = await client.responses.create({
  model: "gpt-5.5",
  input: "Summarize the SeaChat API in one paragraph.",
});
```

## Discovery

`client.models.list()` (`GET /v1/models`) lists available modalities/models. `client.models.get(path)` (`GET /v1/models/{path}`) reads a sub-resource; pass a modality such as `"image"` or `"embedding"` to enumerate that modality's deployment-specific model ids. Filter to `availability.state === "live_ok"` before using one.

```bash
curl https://seachat.ai/v1/models \
  -H "Authorization: Bearer $SEACHAT_API_KEY"
```