Весело
Весело

Справочник API

Все методы API Весело: /v1/chat/completions, /v1/models, /v1/balance и /v1/usage — поля запроса и ответа, примеры JSON и коды ошибок.

Обновлено:

Базовый адрес — https://veselo.ai/v1. Запросы и ответы — JSON в UTF-8; у POST нужен заголовок Content-Type: application/json, без него или с неверным JSON придёт 400 invalid_request. Ключ — Authorization: Bearer sk-vsl-… или x-api-key: sk-vsl-…. Ошибки — в формате OpenAI, у /v1/messages — в формате Anthropic.

МетодКлючЧто делает
POST /v1/chat/completionsдаответ модели — целиком или потоком
POST /v1/messagesдаответ модели в формате Anthropic — для Claude Code и SDK Anthropic
GET /v1/modelsнетвсе модели с ценами в рублях
GET /v1/models/{vendor}/{model}нетодна модель
GET /v1/balanceдасколько денег доступно
GET /v1/usageдарасход по дням и моделям
POST /v1/images/generationsданарисовать картинки — ссылки или base64 и цена в рублях
POST /v1/audio/speechдаозвучить текст — в ответ MP3
POST /v1/audio/musicдамузыка по описанию — ссылка на MP3 и цена в рублях
POST /v1/videosдазапустить видео — задача
GET /v1/videos/{id}дастатус видео и ссылка на ролик
GET /v1/openapi.jsonнетописание API в формате OpenAPI 3.1

Другие адреса отвечают 404 not_found. MCP — отдельная точка https://veselo.ai/mcp, см. MCP-сервер.

POST /v1/chat/completions

Ответ модели на список сообщений, как в OpenAI Chat Completions. Подробно — Чат, Стриминг, Вызов функций, Ответ в JSON, Картинки во входе.

Поля запроса

ПолеТипЧто это
modelстрока, обязательноid модели из GET /v1/models
messagesмассив, обязательноот 1 до 2000 сообщений {role, content}; роли — system, user, assistant, tool
streamtrue или falseответ потоком SSE
max_tokensцелое от 1 до 1 000 000потолок длины ответа; от него зависит удержание
max_completion_tokensцелое от 1 до 1 000 000то же, что max_tokens; если заданы оба, берётся это поле
nтолько 1число вариантов ответа
temperature, top_pчислослучайность ответа
top_k, min_p, top_a, repetition_penaltyчисловыборка у открытых моделей
frequency_penalty, presence_penaltyчислоштраф за повторы
stopстрока или массивна чём остановиться
seedцелоеповторяемость ответа, если модель поддерживает
tools, tool_choice, parallel_tool_callsкак у OpenAIвызов функций
response_formatобъектответ в JSON
logprobs, top_logprobs, logit_biasкак у OpenAIвероятности токенов и их сдвиг
reasoning, reasoning_effortобъект или строкасколько думать моделям с рассуждениями
verbosity, prediction, structured_outputsкак у моделипередаются модели как есть

Остальные поля отбрасываются без ошибки и до модели не доходят — например, user, metadata, store, stream_options, functions, function_call. Что из параметров понимает конкретная модель — в её supported_parameters.

Ответ без stream

ПолеЧто это
idchatcmpl- и номер запроса req_… — тот же, что в заголовке x-request-id
objectchat.completion
createdвремя ответа, Unix-время
modelмодель, которая ответила
choices[0].messagerole, content, а при вызове функций — tool_calls; у моделей с рассуждениями может быть reasoning
choices[0].finish_reasonstop, length, tool_calls или content_filter
usage.prompt_tokens, usage.completion_tokens, usage.total_tokensтокены входа, выхода и сумма
usage.cost_rubцена запроса, ₽

В ответе могут быть и другие поля формата OpenAI — например, подробности о токенах в usage. С stream: true ответ идёт потоком SSE, формат — в разделе Стриминг.

curl

curl -i https://veselo.ai/v1/chat/completions \
  -H "Authorization: Bearer $VESELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4.1-flash-ultrafast", "max_tokens": 300, "messages": [{"role": "user", "content": "Объясни в двух предложениях, что такое API."}]}'

Ответ

{
  "id": "chatcmpl-req_5b2e9c0d41f84a7f9e3c2a1b0d6f8e47",
  "object": "chat.completion",
  "created": 1794132000,
  "model": "deepseek/deepseek-v4.1-flash-ultrafast",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "API — это правила, по которым одна программа обращается к другой…" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 19, "completion_tokens": 41, "total_tokens": 60, "cost_rub": 0.01 }
}

Заголовки ответа: x-request-id, x-veselo-cost-rub, x-veselo-balance-rub, x-ratelimit-* — см. Заголовки.

Ошибки: 400 invalid_request; 401 missing_api_key, invalid_api_key; 402 insufficient_balance; 403 key_limit_reached, model_not_allowed, account_blocked; 404 model_not_found; 413 payload_too_large; 422 content_refused; 429 rate_limited; 500 internal_error; 502 upstream_error; 503 model_unavailable, api_disabled; 504 upstream_timeout. Что значит каждая — в разделе Ошибки.

POST /v1/messages

Ответ модели в формате Anthropic Messages: обязательны model, max_tokens и messages. Модели, деньги и лимиты — те же, что у /v1/chat/completions; ошибки — в формате Anthropic. Поля, события потока и примеры — Claude Code и формат Anthropic.

POST /v1/images/generations

У нейросетей Студии ещё quality и заголовок Idempotency-Key; n — только 1. Подробно — Картинки.

Обязательны model и prompt; необязательны n, size или aspect_ratio, response_format, output_format, seed. Ответ: {created, data: [{url} | {b64_json}], usage: {cost_rub}}. Ссылки живут 7 дней. Поля, деньги, ошибки и примеры — Картинки.

POST /v1/audio/speech

Обязательны model и input; необязательны voice, response_format (только mp3) и заголовок Idempotency-Key. Ответ — сам MP3 (audio/mpeg), цена — в x-veselo-cost-rub. Подробно — Озвучка.

POST /v1/audio/music

Обязательны model и prompt; необязательны response_format (url или b64_json) и заголовок Idempotency-Key. Ответ: {created, data: [{url}], usage: {cost_rub}}. Подробно — Музыка.

GET /v1/models

Все модели, которые можно звать, с ценами в рублях. Ключ не нужен. Ответ — {"object": "list", "data": [модель, …]}; поля модели — в разделе Модели.

curl

curl https://veselo.ai/v1/models

Ответ

{
  "object": "list",
  "data": [
    {
      "id": "deepseek/deepseek-v4.1-flash-ultrafast",
      "object": "model",
      "created": 1735689600,
      "owned_by": "deepseek",
      "name": "DeepSeek V4.1 Flash Ultrafast",
      "type": "text",
      "context_length": 1048576,
      "max_output_tokens": 16384,
      "input_modalities": ["text"],
      "output_modalities": ["text"],
      "pricing_rub": { "input_per_1m": 40, "output_per_1m": 120 },
      "supported_parameters": ["max_tokens", "temperature", "tools", "tool_choice", "response_format", "structured_outputs"]
    }
  ]
}

Цены в примере условные.

GET /v1/models/{vendor}/{model}

Одна модель — тот же объект, что в списке. Ключ не нужен. id со слешем пишется в путь как есть. Ошибки: 404 model_not_found — такой модели нет, 403 model_not_allowed — модель не продаётся.

curl

curl https://veselo.ai/v1/models/deepseek/deepseek-v4.1-flash-ultrafast

GET /v1/balance

Сколько денег доступно для запросов — по всему аккаунту. Запрос бесплатный.

curl

curl https://veselo.ai/v1/balance -H "Authorization: Bearer $VESELO_API_KEY"

Ответ

{
  "object": "balance",
  "api_balance_rub": 48.37,
  "held_rub": 0.12,
  "cashback_rub": 1.84,
  "available_rub": 48.25,
  "available": "48,25 ₽",
  "topup_url": "https://veselo.ai/developer/wallet"
}
ПолеЧто это
api_balance_rubна API-счёте, ₽; может быть чуть меньше нуля, если ответ вышел дороже удержания
held_rubудержано под идущие запросы, ₽
cashback_rubиз них кэшбэк, ₽: тратится первым, деньгами не возвращается
available_rubсколько можно потратить сейчас: свободное на API-счёте
topup_urlгде пополнить API-счёт
availableто же строкой для людей

GET /v1/usage

Расход по дням и моделям — по всему аккаунту. Параметр days — за сколько последних суток, от 1 до 90, по умолчанию 30.

curl

curl "https://veselo.ai/v1/usage?days=7" -H "Authorization: Bearer $VESELO_API_KEY"

Ответ

{
  "object": "usage",
  "days": 7,
  "total_rub": 3.41,
  "data": [
    { "day": "2026-11-07", "model": "deepseek/deepseek-v4.1-flash-ultrafast", "requests": 112, "input_tokens": 254300, "output_tokens": 61840, "cost_rub": 2.86 },
    { "day": "2026-11-06", "model": "deepseek/deepseek-v4.1-flash-ultrafast", "requests": 23, "input_tokens": 41200, "output_tokens": 9950, "cost_rub": 0.55 }
  ]
}
ПолеЧто это
daysза сколько суток отчёт
total_rubпотрачено за это время, ₽
data[].dayдата по Москве, YYYY-MM-DD; строки — от новых дней к старым
data[].modelмодель
data[].requestsзапросов, включая запросы с ошибкой — они стоят 0
data[].input_tokens, data[].output_tokensтокены входа и выхода
data[].cost_rubпотрачено, ₽

Запросы, которые ещё идут, в отчёт не попадают.

POST /v1/videos и GET /v1/videos/{id}

Видео — задача: запуск отвечает 202 с id, статус — GET /v1/videos/{id}. Поля, статусы, деньги и повторы — Видео.

GET /v1/openapi.json

Описание API в формате OpenAPI 3.1 — для Postman, генераторов клиентов и ИИ-агентов. Ключ не нужен.

← MCP · Ошибки →

Вся документация одним текстом · Все модели и цены