{"openapi":"3.1.0","info":{"title":"НейроХудожник Скилл","version":"1.0.0","description":"Скилл генерации изображений, видео и аудио для AI-агентов. Оптимизировано для минимального расхода токенов.","contact":{"name":"НейроХудожник Скилл","url":"https://neuroartist.ru"}},"servers":[{"url":"https://api.neuroartist.ru","description":"Production"},{"url":"http://localhost:3000","description":"Development"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"models","description":"Управление моделями"},{"name":"generate","description":"Генерация контента"},{"name":"files","description":"Загрузка файлов"},{"name":"billing","description":"Баланс и биллинг"}],"paths":{"/api/v1/models":{"get":{"operationId":"listModels","tags":["models"],"summary":"Список моделей","description":"Возвращает список всех доступных моделей для генерации.","parameters":[{"name":"category","in":"query","description":"Фильтр по категории","schema":{"type":"string","enum":["text-to-image","image-to-image","text-to-video","image-to-video","audio","3d"]}},{"name":"format","in":"query","description":"Формат ответа (compact для агентов)","schema":{"type":"string","enum":["full","compact"],"default":"full"}}],"responses":{"200":{"description":"Список моделей","content":{"application/json":{"schema":{"type":"object","properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}}}}}}}},"/api/v1/models/{modelId}/schema":{"get":{"operationId":"getModelSchema","tags":["models"],"summary":"Схема модели","description":"Возвращает JSON Schema параметров модели.","parameters":[{"name":"modelId","in":"path","required":true,"description":"ID модели (например: fal-ai/flux/schnell)","schema":{"type":"string"}},{"name":"format","in":"query","description":"Формат схемы","schema":{"type":"string","enum":["full","compact"],"default":"compact"}}],"responses":{"200":{"description":"Схема модели","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelSchema"}}}},"404":{"description":"Модель не найдена","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/generate":{"post":{"operationId":"createGeneration","tags":["generate"],"summary":"Создать генерацию","description":"Запускает генерацию контента. Поддерживает синхронный и асинхронный режимы.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"},"examples":{"textToImage":{"summary":"Text-to-Image","value":{"model":"fal-ai/flux/schnell","input":{"prompt":"A beautiful sunset over mountains","image_size":"landscape_16_9","num_images":1},"sync":true}},"imageToImage":{"summary":"Image-to-Image","value":{"model":"fal-ai/flux/dev","input":{"prompt":"Make it look like a painting","image_url":"https://cdn.neuroartist.ru/...","strength":0.75}}}}}}},"responses":{"200":{"description":"Результат генерации (sync: true)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationResult"}}}},"202":{"description":"Генерация поставлена в очередь (sync: false)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationQueued"}}}},"400":{"description":"Неверные параметры","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Недостаточно средств","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Превышен лимит запросов","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/requests/{requestId}":{"get":{"operationId":"getGenerationStatus","tags":["generate"],"summary":"Статус генерации","description":"Возвращает текущий статус и результат генерации.","parameters":[{"name":"requestId","in":"path","required":true,"description":"ID запроса генерации","schema":{"type":"string"}}],"responses":{"200":{"description":"Статус генерации","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationResult"}}}},"404":{"description":"Запрос не найден","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/requests/{requestId}/stream":{"get":{"operationId":"streamGenerationStatus","tags":["generate"],"summary":"SSE стрим статуса","description":"Server-Sent Events для отслеживания прогресса генерации в реальном времени.","parameters":[{"name":"requestId","in":"path","required":true,"description":"ID запроса генерации","schema":{"type":"string"}}],"responses":{"200":{"description":"SSE stream","content":{"text/event-stream":{"schema":{"type":"string","description":"События: status, log, completed, failed. Формат: event: <type>\\ndata: <json>\\n\\n"}}}}}}},"/api/v1/upload":{"post":{"operationId":"uploadFile","tags":["files"],"summary":"Загрузить файл","description":"Загружает файл для использования в генерациях (img2img, video и т.д.).","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Файл для загрузки"}}}},"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"string","description":"Base64-encoded данные или data URL","example":"data:image/png;base64,iVBORw0K..."},"mime_type":{"type":"string","description":"MIME тип (если data не data URL)","example":"image/png"},"filename":{"type":"string","description":"Имя файла","example":"image.png"}}}}}},"responses":{"200":{"description":"Файл загружен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadedFile"}}}},"400":{"description":"Неверный формат файла","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/balance":{"get":{"operationId":"getBalance","tags":["billing"],"summary":"Проверить баланс","description":"Возвращает текущий баланс и информацию о тире.","responses":{"200":{"description":"Информация о балансе","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API ключ в формате `na_live_xxx` (production) или `na_test_xxx` (sandbox)"}},"schemas":{"Model":{"type":"object","required":["id","name","category"],"properties":{"id":{"type":"string","description":"Уникальный ID модели","example":"fal-ai/flux/schnell"},"name":{"type":"string","description":"Название модели","example":"FLUX.1 Schnell"},"category":{"type":"string","enum":["text-to-image","image-to-image","text-to-video","image-to-video","audio","3d"],"description":"Категория модели"},"description":{"type":"string","description":"Описание модели"},"priceRub":{"type":"number","description":"Цена за единицу в рублях","example":1.35},"priceUnit":{"type":"string","description":"Единица измерения цены","enum":["megapixels","images","seconds","videos"],"example":"megapixels"}}},"ModelSchema":{"type":"object","required":["required","properties"],"properties":{"required":{"type":"array","items":{"type":"string"},"description":"Обязательные параметры"},"properties":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"type":"string"},"description":{"type":"string"},"default":{},"enum":{"type":"array","items":{"type":"string"}},"minimum":{"type":"number"},"maximum":{"type":"number"}}}}}},"GenerateRequest":{"type":"object","required":["model","input"],"properties":{"model":{"type":"string","description":"ID модели","example":"fal-ai/flux/schnell"},"input":{"type":"object","description":"Параметры модели (см. схему модели)","additionalProperties":true},"sync":{"type":"boolean","default":false,"description":"true = ждать результат, false = вернуть ID для поллинга"},"webhook_url":{"type":"string","format":"uri","description":"URL для вебхука по завершению"}}},"GenerationQueued":{"type":"object","required":["id","status","model"],"properties":{"id":{"type":"string","description":"ID запроса для поллинга","example":"req_abc123"},"status":{"type":"string","enum":["queued"]},"model":{"type":"string","example":"fal-ai/flux/schnell"},"poll_url":{"type":"string","format":"uri","description":"URL для проверки статуса"},"stream_url":{"type":"string","format":"uri","description":"URL для SSE стрима"}}},"GenerationResult":{"type":"object","required":["id","status","model"],"properties":{"id":{"type":"string","example":"req_abc123"},"status":{"type":"string","enum":["queued","in_progress","completed","failed"]},"model":{"type":"string","example":"fal-ai/flux/schnell"},"output":{"type":"object","description":"Результат генерации (зависит от модели)","properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL изображения на CDN"},"width":{"type":"integer"},"height":{"type":"integer"}}}},"video":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"duration":{"type":"number"}}}}},"processing_time_ms":{"type":"integer","description":"Время обработки в мс"},"cost_rub":{"type":"number","description":"Стоимость генерации в рублях"},"error":{"type":"string","description":"Сообщение об ошибке (если status=failed)"}}},"UploadedFile":{"type":"object","required":["file_id","url","provider_url"],"properties":{"file_id":{"type":"string","format":"uuid","description":"ID файла"},"url":{"type":"string","format":"uri","description":"URL на нашем CDN (для отображения)"},"provider_url":{"type":"string","format":"uri","description":"URL для использования в генерациях"},"mime_type":{"type":"string","example":"image/png"},"size_bytes":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","description":"Время истечения ссылки"}}},"Balance":{"type":"object","required":["balance_rub","tier"],"properties":{"balance_rub":{"type":"number","description":"Текущий баланс в рублях","example":1250.5},"tier":{"type":"integer","minimum":1,"maximum":4,"description":"Текущий тир (1-4)"},"rate_limit":{"type":"integer","description":"Лимит запросов в минуту","example":50},"total_spent_rub":{"type":"number","description":"Всего потрачено (для повышения тира)"}}},"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Описание ошибки"},"code":{"type":"string","enum":["UNAUTHORIZED","INSUFFICIENT_BALANCE","RATE_LIMITED","NOT_FOUND","INVALID_PARAMS","PROVIDER_ERROR"],"description":"Код ошибки"},"details":{"type":"object","description":"Дополнительные детали"}}}}}}