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

# Как работать с текстом

> Отправка запросов к текстовым моделям через Chat Completions API

В этом разделе вы узнаете, как отправлять запросы к текстовым моделям через SpeShu.AI и получать ответы.

<Note>
  Подробное описание endpoint — в [API Reference](/docs/api-reference/chat/completions).
</Note>

## Endpoint

```
POST https://speshu.ai/api/v1/chat/completions
```

Этот метод принимает историю диалога и возвращает ответ модели.

## Основные параметры

| Параметр      | Описание                                              |
| ------------- | ----------------------------------------------------- |
| `model`       | ID модели (например, `openai/gpt-5.5`)                |
| `messages`    | массив сообщений диалога                              |
| `prompt`      | строка с текстом (можно использовать вместо messages) |
| `temperature` | влияет на вариативность ответа (по умолчанию 1.0)     |
| `max_tokens`  | ограничение длины ответа                              |
| `stream`      | включает потоковую выдачу                             |

<Note>
  Нужно передать либо `messages`, либо `prompt`. Если используется `prompt`, он автоматически превращается в сообщение от пользователя.
</Note>

## Дополнительные настройки

| Параметр                | Описание                   |
| ----------------------- | -------------------------- |
| `max_completion_tokens` | аналог max\_tokens         |
| `top_p`                 | параметр выборки токенов   |
| `frequency_penalty`     | снижает повторения         |
| `presence_penalty`      | поощряет новые темы        |
| `response_format`       | задаёт структуру ответа    |
| `tools` и `tool_choice` | работа с функциями         |
| `reasoning`             | параметры reasoning        |
| `web_search_options`    | встроенный поиск           |
| `provider`              | выбор провайдера           |
| `user`                  | идентификатор пользователя |

## Формат messages

Каждое сообщение содержит роль и содержимое:

| Поле      | Описание                |
| --------- | ----------------------- |
| `role`    | кто отправил сообщение  |
| `content` | текст или массив частей |

### Роли

| Роль        | Описание                     |
| ----------- | ---------------------------- |
| `system`    | задаёт поведение модели      |
| `developer` | дополнительные инструкции    |
| `user`      | запрос пользователя          |
| `assistant` | ответ модели                 |
| `tool`      | результат работы инструмента |

### Примеры content

```json theme={null} theme={null}
// обычный текст
{ "role": "user", "content": "Привет!" }

// с медиа
{
  "role": "user",
  "content": [
    { "type": "text", "text": "Что изображено?" },
    { "type": "image_url", "image_url": { "url": "https://example.com/img.jpg" } }
  ]
}
```

Подробнее о передаче медиа — в гайде [Передача медиа на вход](/docs/gaidy/media-input).

## Простой пример

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  import OpenAI from 'openai';

  const openai = new OpenAI({
    baseURL: 'https://speshu.ai/api/v1',
    apiKey: '<SPESHU_AI_API_KEY>'
  });

  const completion = await openai.chat.completions.create({
    model: 'openai/gpt-5.5',
    messages: [
      { role: 'system', content: 'Ты полезный ассистент.' },
      { role: 'user', content: 'Напиши хайку о программировании' }
    ],
    temperature: 0.7,
    max_tokens: 100
  });

  console.log(completion.choices[0].message.content);
  ```

  ```python Python theme={null} theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://speshu.ai/api/v1",
      api_key="<SPESHU_AI_API_KEY>"
  )

  completion = client.chat.completions.create(
      model="openai/gpt-5.5",
      messages=[
          {"role": "system", "content": "Ты полезный ассистент."},
          {"role": "user", "content": "Напиши хайку о программировании"}
      ],
      temperature=0.7,
      max_tokens=100
  )

  print(completion.choices[0].message.content)
  ```

  ```bash cURL theme={null} theme={null}
  curl -X POST "https://speshu.ai/api/v1/chat/completions" \
    -H "Authorization: Bearer <SPESHU_AI_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "messages": [
        {"role": "system", "content": "Ты полезный ассистент."},
        {"role": "user", "content": "Напиши хайку о программировании"}
      ],
      "temperature": 0.7,
      "max_tokens": 100
    }'
  ```
</CodeGroup>

## Структура ответа

```json theme={null} theme={null}
{
  "id": "gen_581761234567890123",
  "object": "chat.completion",
  "created": 1703001234,
  "model": "openai/gpt-5.5",
  "provider": "openai-direct",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Код течёт рекой\nБаги тают на рассвете\nРелиз близко..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 20,
    "total_tokens": 45,
    "cost_rub": 0.15,
    "cost": 0.15
  }
}
```

### Что в ответе

| Поле                         | Описание                       |
| ---------------------------- | ------------------------------ |
| `id`                         | идентификатор запроса          |
| `provider`                   | кто обработал запрос           |
| `choices[0].message.content` | текст ответа                   |
| `finish_reason`              | почему завершилась генерация   |
| `usage`                      | статистика токенов и стоимость |

### Значения finish\_reason

| Значение         | Описание                     |
| ---------------- | ---------------------------- |
| `stop`           | генерация завершена          |
| `length`         | достигнут лимит              |
| `tool_calls`     | модель хочет вызвать функцию |
| `content_filter` | ответ отфильтрован           |

## Стриминг

Для получения ответа по мере генерации установите `stream: true`. Ответ приходит в формате Server-Sent Events (SSE):

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const stream = await openai.chat.completions.create({
    model: 'openai/gpt-5.5',
    messages: [{ role: 'user', content: 'Напиши короткую историю' }],
    stream: true
  });

  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content;
    if (content) {
      process.stdout.write(content);
    }
  }
  ```

  ```python Python theme={null} theme={null}
  stream = client.chat.completions.create(
      model="openai/gpt-5.5",
      messages=[{"role": "user", "content": "Напиши короткую историю"}],
      stream=True
  )

  for chunk in stream:
      content = chunk.choices[0].delta.content
      if content:
          print(content, end="", flush=True)
  ```
</CodeGroup>

## Пример диалога

Для ведения диалога передавайте историю сообщений:

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  import OpenAI from 'openai';

  const openai = new OpenAI({
    baseURL: 'https://speshu.ai/api/v1',
    apiKey: '<SPESHU_AI_API_KEY>'
  });

  const messages = [
    { role: 'system', content: 'Ты помощник по программированию.' },
    { role: 'user', content: 'Как создать массив в JavaScript?' },
    { role: 'assistant', content: 'В JavaScript массив создаётся так: const arr = [1, 2, 3];' },
    { role: 'user', content: 'А как добавить элемент?' }
  ];

  const completion = await openai.chat.completions.create({
    model: 'openai/gpt-5.5',
    messages: messages
  });

  // Модель ответит с учётом контекста диалога
  console.log(completion.choices[0].message.content);
  ```

  ```python Python theme={null} theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://speshu.ai/api/v1",
      api_key="<SPESHU_AI_API_KEY>"
  )

  messages = [
      {"role": "system", "content": "Ты помощник по программированию."},
      {"role": "user", "content": "Как создать массив в JavaScript?"},
      {"role": "assistant", "content": "В JavaScript массив создаётся так: const arr = [1, 2, 3];"},
      {"role": "user", "content": "А как добавить элемент?"}
  ]

  completion = client.chat.completions.create(
      model="openai/gpt-5.5",
      messages=messages
  )

  # Модель ответит с учётом контекста диалога
  print(completion.choices[0].message.content)
  ```

  ```bash cURL theme={null} theme={null}
  curl -X POST "https://speshu.ai/api/v1/chat/completions" \
    -H "Authorization: Bearer <SPESHU_AI_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "messages": [
        {"role": "system", "content": "Ты помощник по программированию."},
        {"role": "user", "content": "Как создать массив в JavaScript?"},
        {"role": "assistant", "content": "В JavaScript массив создаётся так: const arr = [1, 2, 3];"},
        {"role": "user", "content": "А как добавить элемент?"}
      ]
    }'
  ```
</CodeGroup>

## Стриминг

Если нужен ответ по частям, включите `stream: true`:

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const stream = await openai.chat.completions.create({
    model: 'openai/gpt-5.5',
    messages: [{ role: 'user', content: 'Напиши короткую историю' }],
    stream: true
  });

  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content;
    if (content) {
      process.stdout.write(content);
    }
  }
  ```

  ```python Python theme={null} theme={null}
  stream = client.chat.completions.create(
      model="openai/gpt-5.5",
      messages=[{"role": "user", "content": "Напиши короткую историю"}],
      stream=True
  )

  for chunk in stream:
      content = chunk.choices[0].delta.content
      if content:
          print(content, end="", flush=True)
  ```
</CodeGroup>

## Диалог

Чтобы модель учитывала предыдущие сообщения, передавайте их вместе:

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const messages = [
    { role: 'system', content: 'Ты помощник по программированию.' },
    { role: 'user', content: 'Как создать массив в JavaScript?' },
    { role: 'assistant', content: 'const arr = [1, 2, 3];' },
    { role: 'user', content: 'Как добавить элемент?' }
  ];

  const completion = await openai.chat.completions.create({
    model: 'openai/gpt-5.5',
    messages
  });

  console.log(completion.choices[0].message.content);
  ```

  ```python Python theme={null} theme={null}
  messages = [
      {"role": "system", "content": "Ты помощник по программированию."},
      {"role": "user", "content": "Как создать массив в JavaScript?"},
      {"role": "assistant", "content": "const arr = [1, 2, 3];"},
      {"role": "user", "content": "Как добавить элемент?"}
  ]

  completion = client.chat.completions.create(
      model="openai/gpt-5.5",
      messages=messages
  )

  print(completion.choices[0].message.content)
  ```

  ```bash cURL theme={null} theme={null}
  curl -X POST "https://speshu.ai/api/v1/chat/completions" \
    -H "Authorization: Bearer <SPESHU_AI_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "messages": [
        {"role": "system", "content": "Ты помощник по программированию."},
        {"role": "user", "content": "Как создать массив в JavaScript?"},
        {"role": "assistant", "content": "const arr = [1, 2, 3];"},
        {"role": "user", "content": "Как добавить элемент?"}
      ]
    }'
  ```
</CodeGroup>

## Практические моменты

### System-сообщение

Через него задаётся стиль и формат ответа. Например: указать язык, длину ответа или формат.

### Temperature

| Значение | Результат                 |
| -------- | ------------------------- |
| 0.0–0.3  | точные ответы             |
| 0.5–0.7  | баланс                    |
| 0.8+     | более свободная генерация |

### Ограничение длины

`max_tokens` помогает контролировать размер ответа и расходы.