Visnea API

Генерация

Один эндпоинт запускает генерацию любой модальности — изображения, видео и озвучку. Модель определяется полем model_id, остальные параметры зависят от её возможностей.

Эндпоинт

POST/v1/generate

Тело запроса

Обязательны только model_id и prompt (промпт не нужен инструментам редактирования — апскейл, удаление фона и т.п.). Остальные поля опциональны и применяются, если модель их поддерживает.

Параметр	Тип	Описание
`model_id`обязательный	string	ID модели из GET /v1/models.
`prompt`обязательный	string	Текст запроса. Лимит длины у каждой модели свой (max_prompt_chars); превышение вернёт ошибку prompt_too_long.
`translate_prompt`	boolean	Автоперевод промпта RU→EN перед отправкой в модель (по умолчанию включён для изображений и видео; на озвучку не влияет). false — отправить как есть.
`num_images`изображения	number	Количество изображений за запрос (1–4). Каждое оплачивается отдельно.
`image_size`изображения	enum	Пресет размера: square_hd, square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9, auto.
`aspect_ratio`	enum	Соотношение сторон из списка aspect_ratios модели, например "16:9".
`quality`изображения	enum	Разрешение (1K \| 2K \| 4K), если модель объявляет этот параметр в form.
`seed`	number	Фиксирует зерно генерации для воспроизводимости.
`negative_prompt`	string	Чего избегать в результате (поддерживается частью моделей).
`output_format`	string	Формат файла результата, если модель это поддерживает.
`voice`озвучка	enum	Голос для TTS-моделей; допустимые значения — в form поля voice.
`reference_images`изображения	string[]	URL входных изображений (img2img/редактирование) — для моделей с supports_refs, не больше max_refs.
`mask_image`изображения	string	URL маски для инпейнта/удаления объектов (модели с requires_mask).
`image_url`видео	string	Стартовый кадр для image-to-video (модели с supports_start_frame).
`end_image_url`видео	string	Финальный кадр (модели с supports_end_frame).
`…form`	mixed	Модельные параметры из form — передаются верхнеуровневыми ключами тела, например duration или resolution.

Точный набор параметров каждой модели — в живом справочнике моделей. Значение вне допустимого списка вернёт ошибку param_unsupported ещё до списания.

Примеры запросов

curl · Изображение

curl https://visnea-labs.com/v1/generate \  -H "Authorization: Bearer sk-visnea-..." \  -H "Content-Type: application/json" \  -d '{    "model_id": "z-image",    "prompt": "портрет в тёплом редакционном свете",    "image_size": "portrait_4_3",    "num_images": 2  }'

curl · Видео

curl https://visnea-labs.com/v1/generate \  -H "Authorization: Bearer sk-visnea-..." \  -H "Content-Type: application/json" \  -d '{    "model_id": "kling-1-5-pro",    "prompt": "полёт дрона над горными вершинами на рассвете",    "aspect_ratio": "16:9",    "duration": 5  }'

curl · Озвучка

curl https://visnea-labs.com/v1/generate \  -H "Authorization: Bearer sk-visnea-..." \  -H "Content-Type: application/json" \  -d '{    "model_id": "elevenlabs-tts",    "prompt": "Текст для озвучки",    "voice": "rachel"  }'

Ответ

Ответ содержит объект generation и актуальный баланс. Синхронные модели сразу возвращают status: "succeeded" со ссылками в results; асинхронные — status: "processing".

200 · response

{  "generation": {    "id": "gen_01hx…",    "model_id": "z-image",    "kind": "image",    "status": "succeeded",    "prompt": "…",    "price_cherries": 4,    "results": [      { "url": "https://visnea-labs.com/files/….png", "width": 1024, "height": 1365 }    ],    "created_at": "2026-07-24T10:00:00Z"  },  "balance": 496}

Статусы:

processing — генерация выполняется, опрашивайте по id;
succeeded — готово, ссылки в results[].url (и result_url);
failed — не получилось; списанные вишенки возвращаются автоматически.

Поллинг результата

Пока статус processing, запрашивайте генерацию раз в 2–5 секунд. Видео может рендериться несколько минут.

GET/v1/generations/{id}

curl

curl https://visnea-labs.com/v1/generations/GEN_ID \  -H "Authorization: Bearer sk-visnea-..."# → { "generation": { "id": "GEN_ID", "status": "processing", … } }# → { "generation": { "id": "GEN_ID", "status": "succeeded", "results": [ … ] } }

Референсы и загрузка файлов

Модели с supports_refs принимают входные изображения в reference_images (до max_refs URL). Если файл лежит локально — сначала загрузите его:

POST/v1/uploads

curl · multipart

curl https://visnea-labs.com/v1/uploads \  -H "Authorization: Bearer sk-visnea-..." \  -F "file=@reference.png"# → { "id": "…", "url": "https://visnea-labs.com/files/….png", … }

В ответе придёт url — используйте его в reference_images, mask_image или image_url.

Улучшение промпта

Отдельный эндпоинт переписывает промпт подробнее и чище на том же языке. Укажите model_id, чтобы ответ учитывал лимит длины этой модели.

POST/v1/generation/improve-prompt

curl

curl https://visnea-labs.com/v1/generation/improve-prompt \  -H "Authorization: Bearer sk-visnea-..." \  -H "Content-Type: application/json" \  -d '{    "prompt": "кот на крыше",    "kind": "image",    "model_id": "z-image"  }'# → { "prompt": "…", "changed": true, "chars": 214, "max_chars": 2000, "over_limit": false }

Чат

Чат-модели работают через отдельный эндпоинт. Первый запрос без session_id создаёт сессию; продолжайте диалог, передавая session_id из ответа.

POST/v1/chat/send

curl

curl https://visnea-labs.com/v1/chat/send \  -H "Authorization: Bearer sk-visnea-..." \  -H "Content-Type: application/json" \  -d '{ "model_id": "gpt-5-5", "message": "Привет!" }'# → { "session_id": "…", "message": { "role": "assistant", "content": "…" }, "balance": 495, "new": true }