Быстрый старт

Первый работающий запрос к SpeShu.AI — за три шага: получить ключ, проверить его, отправить запрос к чату.

Шаг 1 — получите ключ

Зарегистрируйтесь на speshu.ai.
Пополните баланс в профиле. Без положительного остатка платный запрос вернёт 402 insufficient_quota.
Создайте ключ в разделе API-ключи на speshu.ai/profile.

Ключ начинается с sk- и показывается один раз — сохраните его сразу. Формат ключа, заголовки и отзыв разобраны на странице Аутентификация.

cURL

export SPESHU_API_KEY="sk-ваш-ключ"

Шаг 2 — проверьте ключ

Один запрос к балансу доказывает, что ключ принят, и сразу показывает, сколько денег на счёте.

cURL

curl https://speshu.ai/api/v1/balance \
  -H "Authorization: Bearer $SPESHU_API_KEY"

{ "RUB": "1250.00" }

Ответ с суммами — ключ рабочий. Ответ 401 с кодом invalid_api_key — ключ неверный, отозван или истёк. Формат ответа разобран на странице Баланс.

Шаг 3 — первый запрос

Берите модель из каталога и сразу используйте её в запросе. Смысл этого шага — объяснить, почему модель берётся из каталога, а не зашивается константой в коде.

MODEL=$(curl -s https://speshu.ai/api/v1/models | jq -r '.data[0].id')

curl https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$MODEL\",
    \"messages\": [{\"role\": \"user\", \"content\": \"Привет!\"}]
  }"

import os

import requests
from openai import OpenAI

BASE = "https://speshu.ai/api/v1"

catalog = requests.get(f"{BASE}/models", timeout=30).json()["data"]
model = catalog[0]["id"]

client = OpenAI(base_url=BASE, api_key=os.environ["SPESHU_API_KEY"])

response = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Привет!"}],
)

print(response.choices[0].message.content)
print(response.usage.cost.total_cost, "₽")

import OpenAI from "openai";

const BASE = "https://speshu.ai/api/v1";

const catalog = await fetch(`${BASE}/models`).then((r) => r.json());
const model = catalog.data[0].id as string;

const client = new OpenAI({ baseURL: BASE, apiKey: process.env.SPESHU_API_KEY! });

const response = await client.chat.completions.create({
  model,
  messages: [{ role: "user", content: "Привет!" }],
});

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

Ответ приходит в формате OpenAI Chat Completions:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1756800000,
  "model": "<идентификатор из каталога>",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": { "role": "assistant", "content": "Привет! Чем помочь?" }
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 7,
    "total_tokens": 16,
    "cost": { "input_cost": 0.0002, "output_cost": 0.0006, "total_cost": 0.0008 }
  }
}

usage.cost.total_cost — это ровно та сумма в рублях, которая списана с вашего кошелька за этот запрос. Разбор поля — на странице Тарификация и оплата.

Официальный SDK OpenAI работает как есть: достаточно поменять base_url на https://speshu.ai/api/v1 и передать ключ. Код клиента переписывать не нужно.

Выбор модели

Не зашивайте идентификаторы моделей в код. Состав каталога меняется: модели появляются, уходят и отключаются, а идентификаторы переименовываются — и запросы начинают падать с 404 model_not_found без предупреждения. Берите id из ответа GET /api/v1/models и подставляйте его в поле model как есть, без префикса провайдера:

cURL

# первый доступный идентификатор
curl -s https://speshu.ai/api/v1/models | jq -r '.data[0].id'

Python

import requests

model = requests.get(
    "https://speshu.ai/api/v1/models", timeout=30
).json()["data"][0]["id"]

print(model)

Модели для изображений, видео, аудио и музыки живут в отдельном каталоге — GET /api/v1/media/models. Как выбирать по цене, контекстному окну и возможностям, разобрано на странице Модели и цены, формат ответов — в Каталоге моделей и Каталоге медиа-моделей.

Неизвестный идентификатор даёт 404 с кодом model_not_found. Полный разбор кодов — на странице Ошибки.

Потоковый ответ

Добавьте stream: true к тому же запросу — токены придут по мере генерации. Флаг -N у curl отключает буферизацию вывода, без него вы увидите весь ответ разом в самом конце:

cURL

curl -N https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\": \"$MODEL\", \"messages\": [{\"role\": \"user\", \"content\": \"Привет!\"}], \"stream\": true}"

Здесь используется $MODEL из шага 3 — выполните те команды в том же терминале, и переменная будет в области видимости.

Полный разбор кадров, usage в последнем кадре и поведение при обрыве — в гайде Потоковая передача.

Генерация изображения

Медиа работает асинхронно: вы создаёте задачу, получаете taskId и опрашиваете статус. Модель берётся из медиа-каталога.

cURL

MEDIA_MODEL=$(curl -s https://speshu.ai/api/v1/media/models \
  | jq -r '.data[] | select(.media_type == "image") | .id' | head -1)

TASK=$(curl -s https://speshu.ai/api/v1/async/media/tasks \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"model\": \"$MEDIA_MODEL\", \"input\": {\"prompt\": \"Кот в смокинге\"}}" \
  | jq -r '.data.taskId')

# опрос: у завершённой задачи state равен "success"
curl -s "https://speshu.ai/api/v1/async/media/tasks/$TASK" \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data.state, .data.resultJson'

Заголовок Idempotency-Key нужен для безопасного повтора: новый ключ означает новую задачу и повторное списание. Подробности — в Создании задачи и Статусе задачи.

Что проверить, если не работает

401 — ключ не проходит

Ключ не передан, в нём опечатка, он отозван или истёк. Проверьте заголовок Authorization: Bearer и раздел API-ключи в профиле. Формат ключа и его отзыв — на странице Аутентификация.

402 insufficient_quota — не хватает денег

Баланс неположительный. Проверьте остаток через GET /api/v1/balance и пополните его в профиле. Деньги за отказ не списываются: проверка баланса идёт до обращения к модели. Подробности — на странице Тарификация и оплата.

404 model_not_found — модель неизвестна

Идентификатор не найден в GET /api/v1/models либо модель сейчас отключена. Возьмите id из ответа каталога и подставьте его без изменений. Подробности — на странице Модели и цены.

422 content_too_large — запрос не влезает в окно

Входные токены плюс зарезервированный выход превышают context_length выбранной модели. Уменьшите max_completion_tokens, сократите историю диалога или возьмите модель с окном побольше. Повтор с теми же аргументами не поможет. Полный разбор — на странице Ошибки.

Дальше

Модели и цены

Как выбрать модель под задачу

Тарификация и оплата

Как считается стоимость и списываются деньги

Введение в API

Базовый URL, заголовки, форматы ответов

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

Пополнение счёта и организация в кабинете

Начало

Работа с API

О сервисе

Шаг 1 — получите ключ

Шаг 2 — проверьте ключ

Шаг 3 — первый запрос

Выбор модели

Потоковый ответ

Генерация изображения

Что проверить, если не работает

Дальше

Модели и цены

Тарификация и оплата

Введение в API

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

​Шаг 1 — получите ключ

​Шаг 2 — проверьте ключ

​Шаг 3 — первый запрос

​Выбор модели

​Потоковый ответ

​Генерация изображения

​Что проверить, если не работает

​Дальше

Модели и цены

Тарификация и оплата

Введение в API

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

Шаг 1 — получите ключ

Шаг 2 — проверьте ключ

Шаг 3 — первый запрос

Выбор модели

Потоковый ответ

Генерация изображения

Что проверить, если не работает

Дальше