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

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

Подробное описание endpoint — в API Reference.

Endpoint

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

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

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

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

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

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

Параметр	Описание
`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

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

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

Подробнее о передаче медиа — в гайде Передача медиа на вход.

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

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);

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)

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
  }'

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

{
  "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):

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);
  }
}

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)

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

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

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);

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)

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": "А как добавить элемент?"}
    ]
  }'

Стриминг

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

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);
  }
}

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)

Диалог

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

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);

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)

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": "Как добавить элемент?"}
    ]
  }'

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

System-сообщение

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

Temperature

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

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

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

Начало работы

Продвинутые настройки

Генерация медиа

Интеграции

Endpoint

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

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

Формат messages

Роли

Примеры content

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

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

Что в ответе

Значения finish_reason

Стриминг

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

Стриминг

Диалог

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

System-сообщение

Temperature

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

​Endpoint

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

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

​Формат messages

​Роли

​Примеры content

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

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

​Что в ответе

​Значения finish_reason

​Стриминг

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

​Стриминг

​Диалог

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

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

​Temperature

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

Endpoint

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

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

Формат messages

Роли

Примеры content

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

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

Что в ответе

Значения finish_reason

Стриминг

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

Стриминг

Диалог

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

System-сообщение

Temperature

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