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

Практический маршрут от пустого ключа до работающей интеграции. Каждый шаг — один работающий пример, который можно выполнить прямо в терминале.

Трёхшаговая версия этого же материала — на странице Быстрый старт. Здесь больше шагов и разбор того, что происходит на каждом.

Создайте ключ

Ключ создаётся в веб-приложении: откройте speshu.ai/profile, войдите и создайте ключ в разделе API-ключей. Полное значение показывается один раз — сохраните его сразу.

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

Подробности — в разделе Аутентификация.

Проверьте ключ запросом баланса

Это самый дешёвый способ убедиться, что ключ принят: запрос баланса не стоит токенов и не обращается к моделям.

cURL

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

{ "RUB": "1250.00", "USD": "3.75" }

Пустой объект {} — тоже корректный ответ: ключ рабочий, записей в кошельке пока нет.

Ответ 401 с кодом invalid_api_key означает, что ключ недействителен, отозван или истёк. Разбираться нужно в разделе API-ключей в профиле, а не в коде.

Перед платным запросом баланс должен быть положительным, иначе придёт 402 insufficient_quota. Пополнение — на speshu.ai/profile.

Возьмите идентификатор модели из каталога

Идентификаторы текстовых моделей не зашивайте в код — состав каталога меняется. Возьмите его из ответа API:

cURL

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

.data[0] — первый элемент, чтобы пример был запускаемым. В своём коде выбирайте по cost_completion, context_length и наличию зрения. Формат ответа разобран в Каталоге моделей.

Выполните первый запрос в чат

curl -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$TEXT_MODEL\",
    \"messages\": [{\"role\": \"user\", \"content\": \"Привет! Ответь одним предложением.\"}]
  }" | jq -r '.choices[0].message.content, .usage.cost.total_cost'

import os
import requests

BASE = "https://speshu.ai/api/v1"
headers = {"Authorization": f"Bearer {os.environ['SPESHU_API_KEY']}"}

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

response = requests.post(
    f"{BASE}/chat/completions",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "model": model,
        "messages": [{"role": "user", "content": "Привет! Ответь одним предложением."}],
    },
    timeout=300,
)
response.raise_for_status()
body = response.json()

print(body["choices"][0]["message"]["content"])
print("списано:", body["usage"]["cost"]["total_cost"], "₽")

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://speshu.ai/api/v1",
  apiKey: process.env.SPESHU_API_KEY!,
});

const models = await client.models.list();
const model = models.data[0].id;

const completion = await client.chat.completions.create({
  model,
  messages: [{ role: "user", content: "Привет! Ответь одним предложением." }],
});

console.log(completion.choices[0].message?.content);
console.log("списано:", completion.usage?.cost?.total_cost, "₽");

usage.cost.total_cost — сумма, списанная с кошелька в рублях. Это единственное поле, по которому стоит считать расход. Подробнее — в гайде по учёту средств.

Включите потоковую передачу

Тот же запрос с stream: true отдаёт ответ по частям через SSE. В терминале curl -N отключает буферизацию — иначе вы увидите весь ответ разом в самом конце.

cURL

curl -N -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$TEXT_MODEL\",
    \"stream\": true,
    \"messages\": [{\"role\": \"user\", \"content\": \"Напиши три абзаца про океан.\"}]
  }" \
  | grep '^data: ' \
  | sed 's/^data: //'

В Python:

Python

import json
import os

import requests

response = requests.post(
    "https://speshu.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['SPESHU_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": os.environ["TEXT_MODEL"],
        "stream": True,
        "messages": [{"role": "user", "content": "Напиши три абзаца про океан."}],
    },
    stream=True,
    timeout=300,
)
response.raise_for_status()

for line in response.iter_lines():
    if not line or not line.startswith(b"data: "):
        continue
    payload = line[len(b"data: "):]
    if payload == b"[DONE]":
        break
    chunk = json.loads(payload)
    if "error" in chunk:
        raise RuntimeError(chunk["error"]["message"])
    for choice in chunk.get("choices", []):
        print(choice.get("delta", {}).get("content", ""), end="", flush=True)
print()

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

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

Загрузите файл в хранилище

Изображения и документы проще всего передавать публичной ссылкой. Загрузка в хранилище возвращает её.

cURL

curl -s https://speshu.ai/api/v1/storage/upload \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -F "file=@photo.jpg" \
  -F "asset_type=chat_upload"

{
  "asset_id": "0199...",
  "filename": "photo.jpg",
  "size": 245760,
  "asset_type": "chat_upload",
  "url": "https://cdn.example.com/uploads/.../0199....jpg",
  "mime_type": "image/jpeg"
}

Сохраните ссылку в переменную — она понадобится на следующем шаге:

export FILE_URL=$(curl -s https://speshu.ai/api/v1/storage/upload \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -F "file=@photo.jpg" \
  | jq -r '.url')
echo "$FILE_URL"

Тело запроса — только multipart/form-data, предел — 100 МБ. Разбор — в Загрузке файла.

Изображение может быть перекодировано без потерь, если в таком виде файл меньше, поэтому size в ответе бывает меньше отправленного размера. Это норма.

Отправьте изображение в модель

Ссылка из шага выше подставляется в блок image_url:

cURL

curl -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$TEXT_MODEL\",
    \"messages\": [{
      \"role\": \"user\",
      \"content\": [
        {\"type\": \"text\", \"text\": \"Опиши, что изображено на фотографии.\"},
        {\"type\": \"image_url\", \"image_url\": {\"url\": \"$FILE_URL\", \"detail\": \"auto\"}}
      ]
    }]
  }" | jq -r '.choices[0].message.content'

Не каждая модель принимает изображения. Модель без зрения отвергнет запрос целиком с 400 invalid_request — картинка не будет молча проигнорирована. Все четыре типа блоков контента разобраны в гайде по медиавводу.

Создайте медиа-задачу и дождитесь результата

Генерация изображений, видео, аудио и музыки живёт в отдельном API: запрос создаёт задачу, оплата — сразу при создании, результат приходит по опросу.

cURL

TASK_ID=$(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": "nano-banana-2", "input": {"prompt": "Кот в смокинге, студийный свет"}}' \
  | jq -r '.data.taskId')
echo "$TASK_ID"

Опрос:

cURL

curl -s "https://speshu.ai/api/v1/async/media/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data.state'

Готовый цикл ожидания на Python:

Python

import json
import os
import time

import requests

BASE = "https://speshu.ai/api/v1"
headers = {"Authorization": f"Bearer {os.environ['SPESHU_API_KEY']}"}

created = requests.post(
    f"{BASE}/async/media/tasks",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "model": "nano-banana-2",
        "input": {"prompt": "Кот в смокинге, студийный свет"},
    },
    timeout=60,
)
created.raise_for_status()
task_id = created.json()["data"]["taskId"]

while True:
    task = requests.get(
        f"{BASE}/async/media/tasks/{task_id}", headers=headers, timeout=30
    ).json()["data"]

    if task["state"] == "success":
        print(json.loads(task["resultJson"])["resultUrls"][0])
        break
    if task["state"] == "fail":
        raise RuntimeError(f"{task['failCode']}: {task['failMsg']}")

    time.sleep(3)

Деньги списываются при создании задачи, а не при успешном результате. Не переотправляйте создание вслепую: повтор с тем же Idempotency-Key вернёт исходную задачу, повтор с новым — создаст новую и спишет снова. Подробности — в Создании задачи.

Что дальше

Запрос в чат

Роли, блоки контента, параметры генерации

Потоковая передача

SSE, [DONE] и кадр со списанием

Вызов функций

Полный цикл вызова инструмента

Медиаввод

Ссылки, base64 и хранилище

Если что-то не работает

401 invalid_api_key на первом же запросе

Проверьте три вещи: в переменной окружения лежит полное значение с префиксом sk-, в ней нет кавычек и переносов строки, ключ не отозван в профиле. Отладочный вывод: echo "$SPESHU_API_KEY" | wc -c.

404 model_not_found

Идентификатор устарел или скопирован с ошибкой. Возьмите его заново из GET /api/v1/models и подставьте как есть — без префикса и без обрезки. Каталог меняется, и список в коде устаревает молча.

402 insufficient_quota

На балансе нет положительной суммы. Пополнение — в веб-приложении на speshu.ai/profile. Баланс проверяют до обращения к модели. Деньги за отказ не списываются.

400 invalid_request на запрос с изображением

Выбранная модель не принимает зрение. Возьмите другую модель из каталога. Подробнее — в разделе Модели и цены.

Поток отдаётся целиком в конце, а не по частям

В curl не хватает -N: без него клиент буферизует вывод. В HTTP-клиенте проверьте, что вы читаете тело по мере прихода, а не целиком.

413 payload_too_large на загрузке

Файл больше 100 МБ либо исчерпана квота хранилища. Эндпоинта, отдающего текущую квоту, на /api/v1 нет — о лимите вы узнаёте только по факту отказа.

Всё остальное

Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки. Таймауты и квоты — в разделе Лимиты.

Возможности моделей

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

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

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

Что дальше

Запрос в чат

Потоковая передача

Вызов функций

Медиаввод

Если что-то не работает

​Что дальше

Запрос в чат

Потоковая передача

Вызов функций

Медиаввод

​Если что-то не работает

Что дальше

Если что-то не работает