---
title: "Справочник API"
description: "Все методы API Весело: /v1/chat/completions, /v1/models, /v1/balance и /v1/usage — поля запроса и ответа, примеры JSON и коды ошибок."
url: https://veselo.ai/docs/reference
updated: 2026-11-14T20:55:06.831Z
---

# Справочник API

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

Обновлено: 14 ноября 2026 г.

Базовый адрес — `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](https://veselo.ai/docs/errors), у `/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-сервер](https://veselo.ai/docs/mcp).

## POST /v1/chat/completions

Ответ модели на список сообщений, как в OpenAI Chat Completions. Подробно — [Чат](https://veselo.ai/docs/chat), [Стриминг](https://veselo.ai/docs/streaming), [Вызов функций](https://veselo.ai/docs/tools), [Ответ в JSON](https://veselo.ai/docs/structured-output), [Картинки во входе](https://veselo.ai/docs/vision).

**Поля запроса**

| Поле | Тип | Что это |
| --- | --- | --- |
| `model` | строка, обязательно | id модели из `GET /v1/models` |
| `messages` | массив, обязательно | от 1 до 2000 сообщений `{role, content}`; роли — `system`, `user`, `assistant`, `tool` |
| `stream` | true или 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`

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

В ответе могут быть и другие поля формата OpenAI — например, подробности о токенах в `usage`. С `stream: true` ответ идёт потоком SSE, формат — в разделе [Стриминг](https://veselo.ai/docs/streaming).

**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-*` — см. [Заголовки](https://veselo.ai/docs/headers).

**Ошибки:** 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`. Что значит каждая — в разделе [Ошибки](https://veselo.ai/docs/errors).

## POST /v1/messages

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

## POST /v1/images/generations

У нейросетей Студии ещё `quality` и заголовок `Idempotency-Key`; `n` — только 1. Подробно — [Картинки](https://veselo.ai/docs/images).

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

## POST /v1/audio/speech

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

## POST /v1/audio/music

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

## GET /v1/models

Все модели, которые можно звать, с ценами в рублях. Ключ не нужен. Ответ — `{"object": "list", "data": [модель, …]}`; поля модели — в разделе [Модели](https://veselo.ai/docs/models#fields).

**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}`. Поля, статусы, деньги и повторы — [Видео](https://veselo.ai/docs/video).

## GET /v1/openapi.json

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

[← MCP](https://veselo.ai/docs/mcp) · [Ошибки →](https://veselo.ai/docs/errors)

[Вся документация одним текстом](https://veselo.ai/docs/llms.txt) · [Все модели и цены](https://veselo.ai/models)

## Разделы документации

### Начало

- [Быстрый старт](https://veselo.ai/docs)
- [Ключи](https://veselo.ai/docs/auth)
- [Цены и списания](https://veselo.ai/docs/pricing)
- [Модели](https://veselo.ai/docs/models)

### Как сделать

- [Сообщения и параметры](https://veselo.ai/docs/chat)
- [Стриминг](https://veselo.ai/docs/streaming)
- [Вызов функций](https://veselo.ai/docs/tools)
- [Ответ в JSON](https://veselo.ai/docs/structured-output)
- [Провайдеры](https://veselo.ai/docs/providers)
- [Без цензуры](https://veselo.ai/docs/uncensored)
- [Картинки во входе](https://veselo.ai/docs/vision)
- [Картинки](https://veselo.ai/docs/images)
- [Видео](https://veselo.ai/docs/video)
- [Озвучка](https://veselo.ai/docs/speech)
- [Музыка](https://veselo.ai/docs/music)
- [SDK и программы](https://veselo.ai/docs/sdks)
- [Claude Code](https://veselo.ai/docs/anthropic)
- [Ключ для нейросети](https://veselo.ai/docs/agents)
- [MCP](https://veselo.ai/docs/mcp)

### Справочник

- **Методы API**
- [Ошибки](https://veselo.ai/docs/errors)
- [Лимиты](https://veselo.ai/docs/limits)
- [Заголовки](https://veselo.ai/docs/headers)

### Ещё

- [Вопросы](https://veselo.ai/docs/faq)
- [Данные и приватность](https://veselo.ai/docs/privacy)
- [Изменения](https://veselo.ai/docs/changelog)
