API lumv

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

   Войдите на lumv.app, пополните баланс и откройте Кабинет → API → Ключи. Секрет вида sk-lumv-… показывается один раз. Для каждого приложения создайте отдельный ключ; при необходимости задайте срок действия и месячный лимит.

   export LUMV_API_KEY="sk-lumv-..."

2. Выберите модель

   Каталог публичный и не требует ключа. Каждая запись содержит ID, параметры, значения по умолчанию, сценарии и примеры тела запроса. Те же данные — на страницах моделей в разделе Справочник моделей.

   curlJavaScriptPython

   Копировать

   curl https://lumv.app/v1/generation-models

3. Оцените стоимость

   Отправьте будущее тело запроса в POST /v1/generations/estimate. Ответ показывает цену в копейках и кошелёк, с которого пойдёт списание. Задача не создаётся, деньги не списываются.

   curlJavaScriptPython

   estimateКопировать

   curl -X POST https://lumv.app/v1/generations/estimate \
     -H "Authorization: Bearer $LUMV_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
     "model": "model-gpt-image-2",
     "values": {
       "prompt": "Describe the desired result",
       "image_size": "1024x768",
       "quality": "medium",
       "num_images": 1,
       "output_format": "png"
     },
     "inputAssets": []
   }'

4. Запустите генерацию

   То же тело отправьте в POST /v1/generations с уникальным Idempotency-Key. Ответ — HTTP 202 с объектом generation; сохраните generation.id и ключ идемпотентности до повторов.

   curlJavaScriptPython

   generationsКопировать

   curl -X POST https://lumv.app/v1/generations \
     -H "Authorization: Bearer $LUMV_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
     "model": "model-gpt-image-2",
     "values": {
       "prompt": "Describe the desired result",
       "image_size": "1024x768",
       "quality": "medium",
       "num_images": 1,
       "output_format": "png"
     },
     "inputAssets": []
   }'

5. Дождитесь результата

   Опрашивайте статус раз в 3–5 секунд до completed или failed. Ссылки на файлы относительные: добавьте https://lumv.app и передайте тот же ключ.

   curlJavaScriptPython

   Копировать

   curl https://lumv.app/v1/generations/GENERATION_ID \
     -H "Authorization: Bearer $LUMV_API_KEY"

   curl https://lumv.app/v1/generations/GENERATION_ID/assets/ASSET_ID \
     -H "Authorization: Bearer $LUMV_API_KEY" \
     -o result.png

Authorization: Bearer sk-lumv-...

• Без ключа доступны только справочник: GET /v1/generation-models, GET /v1/generation-models/:id, эта документация, llms.txt и llms-full.txt. Даже GET /v1/models требует ключ.
• Cookie веб-сессии не заменяет ключ, а ключ не открывает веб-кабинет.
• Ключ видит только собственные генерации, загрузки и файлы владельца. Чужой, удалённый и несуществующий объект одинаково возвращают 404.
• Отозванный или истёкший ключ получает 401 и больше не может скачивать файлы. Расход всех ключей виден в Кабинет → API → Расход.

Тело запроса

POST /v1/generations/estimate и POST /v1/generations принимают одинаковое JSON-тело. Допустимы только четыре поля верхнего уровня, любое другое даёт 400. Сервер сам выбирает сценарий модели по values и наличию файлов.

Папки проектов

GET /v1/projects возвращает папки, куда владелец ключа может сохранять генерации: свои проекты и командные с правом добавления. Поле team — название команды или null, owned — ваш ли это проект. Передайте id как projectId; без него результат попадает в общую библиотеку без папки.

{
  "object": "list",
  "data": [
    { "id": "PROJECT_ID", "object": "project", "name": "Рекламная кампания", "color": "blue", "team": "Студия", "owned": false }
  ]
}

Оценка цены

costCents — полная цена по тарифу в целых копейках (100 = 1 кредит = 1 RUB). Блок billing показывает, с какого кошелька и сколько будет списано на самом деле. Оценка бесплатна, не резервирует деньги и не фиксирует цену: курс и тариф могут измениться до запуска.

{
  "model": "MODEL_ID",
  "costCents": 1200,
  "currency": "RUB",
  "charged": false,
  "billing": {
    "wallet": "team",
    "teamName": "Студия",
    "unlimited": false,
    "chargeCents": 1200
  }
}

Запуск и идемпотентность

Запуск проверяет параметры и файлы, резервирует цену в одной транзакции с задачей и записью расхода и возвращает HTTP 202 с { generation } и заголовком Retry-After: 3. Безлимитная команда баланс не расходует: costCents в задаче равен 0.

Передавайте уникальный заголовок Idempotency-Key (1–128 печатных ASCII-символов) для каждой новой задачи. Повтор с тем же ключом и тем же телом вернёт уже созданную задачу без второго списания; тот же ключ с другим телом даст 409. Сетевой таймаут не отменяет задачу — повторите запрос с исходным ключом.

Опрос статуса

Проверяйте GET /v1/generations/:id раз в 3–5 секунд. uploading, queued и processing означают, что задача выполняется; финальные статусы — completed и failed. При failed поле error содержит причину, а резерв автоматически возвращается в тот же кошелёк (refunded = 1). Видео и 3D могут обрабатываться несколько минут.

Объект generation

Ответ сокращён: кроме полей ниже есть category, scenarioName, parameters, previewUrl и inputAssets. Все ссылки относительные и требуют тот же Bearer-ключ; поддерживаются GET, HEAD и Range.

{
  "generation": {
    "object": "generation",
    "id": "GENERATION_ID",
    "status": "completed",
    "modelId": "MODEL_ID",
    "prompt": "Неоновый город ночью, кинематографичный свет",
    "reuseValues": { "aspect_ratio": "16:9" },
    "projectId": "PROJECT_ID",
    "projectName": "Рекламная кампания",
    "billingMode": "personal",
    "costCents": 1200,
    "usageUsdMicros": null,
    "refunded": 0,
    "error": null,
    "assets": [
      {
        "id": "0",
        "mediaAssetId": "MEDIA_ASSET_ID",
        "url": "/v1/generations/GENERATION_ID/assets/0",
        "downloadUrl": "/v1/generations/GENERATION_ID/assets/0?download=1",
        "contentType": "image/png",
        "fileName": "result.png",
        "fileSize": 1048576
      }
    ],
    "textOutput": null
  }
}

1. Создайте загрузку

   Укажите профиль, имя, MIME-тип и точный размер файла. Idempotency-Key — 8–128 символов из латиницы, цифр и ._:-. Ответ 201 (или 200 при повторе) содержит uploadUrl и leaseToken; билет действует ограниченное время — см. expiresAt.

   curlJavaScriptPython

   uploadsКопировать

   curl -X POST https://lumv.app/v1/uploads \
     -H "Authorization: Bearer $LUMV_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
     "profile": "reference_image",
     "fileName": "input.png",
     "contentType": "image/png",
     "size": 12345
   }'

   {
     "upload": {
       "id": "UPLOAD_ID",
       "assetId": "ASSET_ID",
       "state": "created",
       "uploadUrl": "/v1/uploads/UPLOAD_ID/content",
       "leaseToken": "LEASE_TOKEN",
       "maximumBytes": 10485760,
       "expiresAt": 1767225600000
     }
   }

2. Передайте байты

   Отправьте точное содержимое файла методом PUT на uploadUrl с Bearer-ключом, тем же Content-Type и заголовком X-Upload-Token.

   curl -X PUT https://lumv.app/v1/uploads/UPLOAD_ID/content \
     -H "Authorization: Bearer $LUMV_API_KEY" \
     -H "Content-Type: image/png" \
     -H "X-Upload-Token: LEASE_TOKEN" \
     --data-binary @input.png

3. Завершите и дождитесь проверки

   Вызовите POST /v1/uploads/:id/complete, затем опрашивайте GET /v1/assets/:assetId до asset.status = ready. Файл со статусом rejected использовать нельзя. Незавершённую загрузку можно отменить через DELETE /v1/uploads/:id.

4. Передайте файл модели

   Используйте assetId в inputAssets: { "fieldName": "image_url", "assetId": "ASSET_ID", "position": 0 }. Имя поля берётся из схемы модели, position задаёт порядок при нескольких файлах.

Кошелёк выбирается для каждого ключа при создании: личный баланс, одна из ваших команд или «Как в аккаунте» — тогда ключ следует за источником списаний в Кабинет → Настройки и переключателем в шапке. Изменить кошелёк ключа можно в Кабинет → API → Ключи; проверить — через billing в ответе estimate (keyBinding показывает режим ключа). Если вы вышли из команды ключа или она архивирована, запросы получают 403 с кодом wallet_unavailable, а не списываются молча с другого кошелька.

• Личный баланс

  billingMode: personal

  Цена резервируется при запуске и списывается с вашего баланса в копейках.

• Команда с предоплатой

  billingMode: team

  Списание идёт с баланса команды так же, как с личного. 402 называет команду, если средств мало.

• Безлимитная команда

  billingMode: team_unlimited

  Баланс не расходуется: costCents = 0, а себестоимость провайдера видна в USD (micro-USD).

Возвраты и уточнение цены

Если генерация завершилась ошибкой, резерв возвращается автоматически. Возвраты и корректировки всегда зачисляются в тот же кошелёк, с которого было списание, даже если вы уже переключились на другой. Для текстовых моделей резерв считается по истории и максимальной длине ответа, а после ответа пересчитывается по фактическим токенам.

Лимиты ключа

У ключа может быть месячный лимит расходов: он учитывает и списания, и резервы активных задач. При превышении запуск возвращает 402. Тот же код означает нехватку средств в выбранном кошельке.

История пополнений — в Кабинет → Платежи, расход по ключам — в API → Расход.

{
  "error": {
    "message": "Недостаточно средств. Нужно 12 кредитов.",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

Лимиты

Активные задачи

До 4 незавершённых генераций и чатов на один ключ

Частота

600 GET и 60 остальных запросов в минуту на ключ и IP

Месячный лимит

Необязательный, на календарный месяц UTC; учитывает резервы активных задач

JSON-тело

До 6 000 000 байт (8 MiB — только предел шлюза)

inputAssets

До 100 ссылок на файлы в одном запросе

Загрузки

reference_image и image_mask — до 10 MiB

Повторы

Повторяйте только 429 и 503 (и сетевые сбои) с экспоненциальной паузой от нескольких секунд и всегда с исходным Idempotency-Key — так повтор не создаст вторую задачу. Заголовок Retry-After гарантированно приходит только в ответе 202 на запуск; если он есть в другом ответе, соблюдайте его. 400, 401, 402, 403, 404, 409 и 422 без изменения запроса не исправятся. Ответы шлюза содержат RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset.

curl -X POST https://lumv.app/v1/chat/completions \
  -H "Authorization: Bearer $LUMV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "model": "claude-fable-5-1",
  "messages": [
    {
      "role": "user",
      "content": "Привет!"
    }
  ],
  "max_tokens": 1024
}'

• POST /v1/chat/completions — messages, max_tokens или max_completion_tokens, temperature, top_p, stream, function tools, tool_choice, parallel_tool_calls и reasoning_effort, если модель его поддерживает.
• POST /v1/responses — input вместо messages, max_output_tokens, instructions, streaming, function tools и previous_response_id для продолжения диалога.
• Ответы сохраняются, пока не передано store: false: GET /v1/responses/:id читает ответ, GET /v1/responses/:id/input_items — его входные элементы, DELETE удаляет.
• С stream: true ответ идёт как SSE. Без потока сервер ждёт результат: 504 означает таймаут — повторите с тем же Idempotency-Key; 502 — модель не смогла ответить.

Что настраивается в кабинете

• Команды — общий кошелёк, приглашения по ссылке с подтверждением администратором, собственные ключи провайдеров и безлимитный режим.
• Проекты — папки для генераций и чатов; проект можно открыть команде на просмотр или с правом добавления. ID проекта передаётся в projectId при запуске по API.
• Библиотека — загруженные и сгенерированные файлы аккаунта с фильтром по проектам.