{
  "openapi": "3.1.0",
  "info": {
    "title": "BlooTube Voice Public API",
    "version": "1.0.0",
    "description": "Официальный программный интерфейс BlooTube Voice для высококачественного нейросетевого синтеза речи, интонационной разметки фрагментов BlooTube Voice Markup (Beta), публичного клонирования голосов и управления словарями произношения.\n\n> **Планируемый базовый адрес API:** `https://api.apexcorelink.org/voice/api/v1` — endpoint ещё не активирован.",
    "contact": {
      "name": "BlooTube AI Support",
      "url": "https://t.me/bloo_kz"
    }
  },
  "servers": [
    {
      "url": "https://api.apexcorelink.org/voice/api/v1",
      "description": "Планируемый базовый адрес API (endpoint ещё не активирован)"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "btv_live_*",
        "description": "API-ключ разработчика (передавать в заголовке `Authorization: Bearer btv_live_...`)"
      }
    },
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "request_id"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "DAILY_QUOTA_EXCEEDED",
                "description": "Стандартизированный код ошибки"
              },
              "message": {
                "type": "string",
                "example": "Недостаточно суточной квоты символов. Требуется: 15000, доступно: 12000 (лимит 600000).",
                "description": "Понятное описание ошибки"
              },
              "request_id": {
                "type": "string",
                "example": "req_8f1b2c3d4e5f6071",
                "description": "Уникальный идентификатор запроса для аудита и технической поддержки"
              },
              "details": {
                "type": "object",
                "description": "Дополнительный структурированный контекст ошибки",
                "example": {
                  "required_chars": 15000,
                  "remaining_chars": 12000,
                  "daily_limit_chars": 600000
                }
              }
            }
          }
        }
      },
      "MeResponse": {
        "type": "object",
        "required": [
          "ok",
          "account",
          "quota",
          "limits",
          "api_key"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "account": {
            "type": "object",
            "properties": {
              "telegram_id": {
                "type": "integer",
                "example": 7894208047
              },
              "username": {
                "type": "string",
                "example": "studio_creator"
              },
              "full_name": {
                "type": "string",
                "example": "Alex Dev"
              },
              "tier": {
                "type": "string",
                "enum": [
                  "pro",
                  "ultra"
                ],
                "example": "pro"
              },
              "tier_display": {
                "type": "string",
                "example": "PRO STUDIO"
              },
              "has_active_license": {
                "type": "boolean",
                "example": true
              },
              "license_expires_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-10-18T00:00:00+00:00"
              },
              "api_access_enabled": {
                "type": "boolean",
                "example": true
              }
            }
          },
          "quota": {
            "type": "object",
            "properties": {
              "daily_limit_chars": {
                "type": "integer",
                "example": 600000
              },
              "used_chars": {
                "type": "integer",
                "example": 45000
              },
              "reserved_chars": {
                "type": "integer",
                "example": 12000
              },
              "remaining_chars": {
                "type": "integer",
                "example": 543000
              },
              "resets_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-09-20T00:00:00+00:00"
              }
            }
          },
          "limits": {
            "type": "object",
            "properties": {
              "in_flight_concurrency": {
                "type": "integer",
                "example": 2
              },
              "active_jobs_running": {
                "type": "integer",
                "example": 1
              },
              "max_job_chars": {
                "type": "integer",
                "example": 600000
              },
              "rate_limits": {
                "type": "object",
                "properties": {
                  "post_tasks_rpm": {
                    "type": "integer",
                    "example": 10
                  },
                  "poll_tasks_rpm": {
                    "type": "integer",
                    "example": 120
                  },
                  "general_rpm": {
                    "type": "integer",
                    "example": 60
                  }
                }
              }
            }
          },
          "api_key": {
            "type": "object",
            "properties": {
              "public_id": {
                "type": "string",
                "example": "btv_pub_a8b2c4d6e8f0"
              },
              "name": {
                "type": "string",
                "example": "Production Pipeline Key"
              },
              "scopes": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "voices:read",
                  "tts:create",
                  "tasks:read",
                  "clones:write"
                ]
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-09-18T14:30:00+00:00"
              }
            }
          }
        }
      },
      "UsageResponse": {
        "type": "object",
        "required": [
          "ok",
          "quota",
          "tier",
          "tier_display",
          "limits"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "quota": {
            "type": "object",
            "properties": {
              "daily_limit_chars": {
                "type": "integer",
                "example": 600000
              },
              "used_chars": {
                "type": "integer",
                "example": 45000
              },
              "reserved_chars": {
                "type": "integer",
                "example": 12000
              },
              "remaining_chars": {
                "type": "integer",
                "example": 543000
              },
              "resets_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-09-20T00:00:00+00:00"
              }
            }
          },
          "tier": {
            "type": "string",
            "example": "pro"
          },
          "tier_display": {
            "type": "string",
            "example": "PRO STUDIO"
          },
          "limits": {
            "type": "object",
            "properties": {
              "in_flight_concurrency": {
                "type": "integer",
                "example": 2
              },
              "max_job_chars": {
                "type": "integer",
                "example": 600000
              },
              "rate_limits": {
                "type": "object",
                "properties": {
                  "post_tasks_rpm": {
                    "type": "integer",
                    "example": 10
                  },
                  "poll_tasks_rpm": {
                    "type": "integer",
                    "example": 120
                  },
                  "general_rpm": {
                    "type": "integer",
                    "example": 60
                  }
                }
              }
            }
          }
        }
      },
      "Voice": {
        "type": "object",
        "required": [
          "id",
          "name",
          "gender",
          "language",
          "is_cloned",
          "is_public"
        ],
        "properties": {
          "id": {
            "type": "string",
            "example": "VOICE_ID_FROM_CATALOG"
          },
          "name": {
            "type": "string",
            "example": "Владимир (Диктор)"
          },
          "gender": {
            "type": "string",
            "enum": [
              "male",
              "female"
            ],
            "example": "male"
          },
          "language": {
            "type": "string",
            "example": "ru"
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "ru",
              "en"
            ]
          },
          "is_cloned": {
            "type": "boolean",
            "example": false
          },
          "is_public": {
            "type": "boolean",
            "example": true
          },
          "source_type": {
            "type": "string",
            "enum": [
              "catalog",
              "cloned"
            ],
            "example": "catalog"
          },
          "created_by_me": {
            "type": "boolean",
            "example": false
          },
          "can_delete": {
            "type": "boolean",
            "example": false
          },
          "description": {
            "type": "string",
            "example": "Уверенный студийный баритон для новостей и обзоров"
          },
          "preview_url": {
            "type": "string",
            "example": "/voice/api/voices/VOICE_ID_FROM_CATALOG/preview.mp3"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "BlooTube",
              "HD",
              "Студийный"
            ]
          }
        }
      },
      "VoicesListResponse": {
        "type": "object",
        "required": [
          "ok",
          "total",
          "voices"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "total": {
            "type": "integer",
            "example": 946
          },
          "voices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Voice"
            }
          }
        }
      },
      "VoiceDetailResponse": {
        "type": "object",
        "required": [
          "ok",
          "voice"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "voice": {
            "$ref": "#/components/schemas/Voice"
          }
        }
      },
      "CreateTaskRequest": {
        "type": "object",
        "required": [
          "text",
          "voice_id"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1200000,
            "example": "Добро пожаловать в студию <speed val=\"1.1\">BlooTube Voice</speed>.",
            "description": "Текст для озвучки с поддержкой BlooTube Voice Markup Beta. Лимиты тарифов: PRO до 600 000, ULTRA до 1 200 000 символов."
          },
          "voice_id": {
            "type": "string",
            "example": "VOICE_ID_FROM_CATALOG",
            "description": "Идентификатор голоса из каталога (/voices) или ID публичного клона"
          },
          "speed": {
            "type": "number",
            "minimum": 0.6,
            "maximum": 1.5,
            "default": 1.0,
            "example": 1.0,
            "description": "Нейросетевой темп речи диктора"
          },
          "volume": {
            "type": "number",
            "minimum": 0.5,
            "maximum": 2.0,
            "default": 1.0,
            "example": 1.0,
            "description": "Коэффициент амплитуды громкости"
          },
          "dsp_speed": {
            "type": "number",
            "minimum": 1.0,
            "maximum": 2.0,
            "default": 1.0,
            "example": 1.0,
            "description": "Монтажное pitch-preserving ускорение темпа без изменения высоты голоса"
          },
          "emotion": {
            "type": [
              "string",
              "null"
            ],
            "default": null,
            "enum": [
              null,
              "neutral",
              "calm",
              "content",
              "excited",
              "sad",
              "angry",
              "scared"
            ],
            "example": null,
            "description": "Эмоциональный тон задачи. По умолчанию null (естественный тон диктора). neutral задается явно."
          },
          "language": {
            "type": "string",
            "default": "ru",
            "example": "ru",
            "description": "Двухбуквенный ISO 639-1 код языка"
          },
          "locale": {
            "type": "string",
            "nullable": true,
            "example": "ru-RU",
            "description": "Региональная локаль произношения (BCP-47)"
          },
          "accent": {
            "type": "string",
            "nullable": true,
            "example": "standard",
            "description": "Специфика акцента или диалекта для выбранного языка"
          },
          "pronunciation_dictionary_id": {
            "type": "string",
            "nullable": true,
            "example": "pdict_4f9a1b2c",
            "description": "ID пользовательского словаря произношения для автоматической подмены терминов"
          },
          "client_task_id": {
            "type": "string",
            "nullable": true,
            "example": "my-pipeline-run-10492",
            "description": "Пользовательский ключ идемпотентности для защиты от дублирующих списаний"
          },
          "callback_url": {
            "type": "string",
            "nullable": true,
            "example": "https://myserver.com/api/voice-webhook",
            "description": "Опциональный Webhook URL для уведомления о завершении синтеза"
          }
        }
      },
      "CreateTaskResponse": {
        "type": "object",
        "required": [
          "ok",
          "task_id",
          "status"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "task_id": {
            "type": "string",
            "format": "uuid",
            "example": "4a18e2c0-8d5f-4a7b-b892-d6c41b80459a"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing"
            ],
            "example": "queued"
          },
          "text_length": {
            "type": "integer",
            "example": 1450
          },
          "chars_reserved": {
            "type": "integer",
            "example": 1450
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-19T14:35:00+00:00"
          }
        }
      },
      "TaskStatusResponse": {
        "type": "object",
        "required": [
          "ok",
          "task_id",
          "status",
          "progress"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "task_id": {
            "type": "string",
            "example": "4a18e2c0-8d5f-4a7b-b892-d6c41b80459a"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing",
              "completed",
              "failed",
              "cancelled"
            ],
            "example": "completed"
          },
          "progress": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "example": 100
          },
          "chunks_completed": {
            "type": "integer",
            "example": 4
          },
          "total_chunks": {
            "type": "integer",
            "example": 4
          },
          "duration_ms": {
            "type": "integer",
            "example": 14250
          },
          "size_bytes": {
            "type": "integer",
            "example": 228400
          },
          "download_url": {
            "type": "string",
            "example": "/voice/api/v1/tasks/4a18e2c0-8d5f-4a7b-b892-d6c41b80459a/download"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-19T19:35:00+00:00"
          },
          "error": {
            "type": "string",
            "example": ""
          }
        }
      },
      "TaskListResponse": {
        "type": "object",
        "required": [
          "ok",
          "tasks",
          "total",
          "limit",
          "offset"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "total": {
            "type": "integer",
            "example": 42
          },
          "limit": {
            "type": "integer",
            "example": 20
          },
          "offset": {
            "type": "integer",
            "example": 0
          },
          "tasks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaskStatusResponse"
            }
          }
        }
      },
      "CancelTaskResponse": {
        "type": "object",
        "required": [
          "ok",
          "task_id",
          "status",
          "chars_refunded"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "task_id": {
            "type": "string",
            "example": "4a18e2c0-8d5f-4a7b-b892-d6c41b80459a"
          },
          "status": {
            "type": "string",
            "example": "cancelled"
          },
          "chars_refunded": {
            "type": "integer",
            "example": 1450
          }
        }
      },
      "CloneItem": {
        "type": "object",
        "required": [
          "voice_id",
          "name",
          "language",
          "status"
        ],
        "properties": {
          "voice_id": {
            "type": "string",
            "example": "cloned_v9a8b7c6"
          },
          "name": {
            "type": "string",
            "example": "Дикторский Голос (Клон)"
          },
          "language": {
            "type": "string",
            "example": "ru"
          },
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "creating",
              "failed"
            ],
            "example": "ready"
          },
          "is_public": {
            "type": "boolean",
            "example": true,
            "description": "После создания клон автоматически доступен в общем каталоге всем пользователям"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-18T10:00:00+00:00"
          }
        }
      },
      "CloneListResponse": {
        "type": "object",
        "required": [
          "ok",
          "clones",
          "used_slots",
          "max_slots"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "used_slots": {
            "type": "integer",
            "example": 1
          },
          "max_slots": {
            "type": "integer",
            "example": 1
          },
          "clones": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CloneItem"
            }
          }
        }
      },
      "PronunciationEntry": {
        "type": "object",
        "required": [
          "text",
          "phonemes"
        ],
        "properties": {
          "text": {
            "type": "string",
            "maxLength": 100,
            "example": "PostgreSQL"
          },
          "phonemes": {
            "type": "string",
            "maxLength": 250,
            "example": "постгрэс кью эл"
          },
          "case_sensitive": {
            "type": "boolean",
            "default": false,
            "example": false
          },
          "alphabet": {
            "type": "string",
            "enum": [
              "sounds-like",
              "ipa"
            ],
            "default": "sounds-like",
            "example": "sounds-like"
          }
        }
      },
      "DictionaryResponse": {
        "type": "object",
        "required": [
          "ok",
          "id",
          "name",
          "entries_count"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "id": {
            "type": "string",
            "example": "pdict_8a1b2c3d"
          },
          "name": {
            "type": "string",
            "example": "Технические термины IT"
          },
          "description": {
            "type": "string",
            "example": "Словарь для озвучки IT документации"
          },
          "entries_count": {
            "type": "integer",
            "example": 15
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-18T12:00:00+00:00"
          }
        }
      }
    }
  },
  "paths": {
    "/me": {
      "get": {
        "summary": "Профиль разработчика, квоты и лимиты",
        "description": "Возвращает информацию о текущем аккаунте, активном тарифе, суточном остатке квоты символов, лимитах параллелизма и метаданных API-ключа.",
        "tags": [
          "Account"
        ],
        "responses": {
          "200": {
            "description": "Успешный ответ профиля",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeResponse"
                }
              }
            }
          },
          "401": {
            "description": "Неверный или отсутствующий API-ключ",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит запросов (Rate Limit)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/usage": {
      "get": {
        "summary": "Текущий расход суточной квоты",
        "description": "Быстрый эндпоинт для проверки доступного суточного объема символов, израсходованных и зарезервированных символов.",
        "tags": [
          "Account"
        ],
        "responses": {
          "200": {
            "description": "Данные квоты",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/schemas/ErrorEnvelope"
          }
        }
      }
    },
    "/capabilities": {
      "get": {
        "summary": "Возможности движка и спецификации",
        "description": "Возвращает полные диапазоны регуляторов (speed, volume, dsp_speed), список утвержденных эмоций, теги разметки Markup Beta и ограничения тарифов.",
        "tags": [
          "Capabilities"
        ],
        "responses": {
          "200": {
            "description": "Спецификация возможностей движка"
          }
        }
      }
    },
    "/voices": {
      "get": {
        "summary": "Каталог голосов",
        "description": "Возвращает каталог студийных нейроголосов и всех публично доступных клонов. Поддерживает фильтрацию по языку, полу и категории.",
        "tags": [
          "Voices"
        ],
        "parameters": [
          {
            "name": "language",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Код языка (например, ru, en)"
          },
          {
            "name": "gender",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ]
            },
            "description": "Пол диктора"
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "catalog",
                "cloned",
                "my_clones"
              ]
            },
            "description": "Категория голосов"
          }
        ],
        "responses": {
          "200": {
            "description": "Список голосов",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VoicesListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/voices/{voice_id}": {
      "get": {
        "summary": "Детальная информация о дикторе",
        "description": "Возвращает расширенные метаданные конкретного голоса по его voice_id.",
        "tags": [
          "Voices"
        ],
        "parameters": [
          {
            "name": "voice_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "VOICE_ID_FROM_CATALOG"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VoiceDetailResponse"
                }
              }
            }
          },
          "404": {
            "description": "Голос не найден",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/tasks": {
      "post": {
        "summary": "Создание задачи озвучки (синтез речи)",
        "description": "Принимает текст для нейросетевого синтеза речи. Поддерживает разметку BlooTube Voice Markup (Beta), словари произношения и защиту от повторного списания квоты по Idempotency-Key.",
        "tags": [
          "Tasks"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Уникальный ключ идемпотентности"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTaskRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Задача принята в обработку",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateTaskResponse"
                }
              }
            }
          },
          "400": {
            "description": "Некорректный запрос или превышение лимита длины задачи",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "402": {
            "description": "Исчерпана суточная квота символов (DAILY_QUOTA_EXCEEDED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Синтаксическая ошибка разметки Markup Beta",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Превышен лимит частоты создания задач (Rate Limit)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Список задач аккаунта",
        "description": "Возвращает список задач, созданных аккаунтом, с поддержкой постраничной пагинации и фильтрации по статусу.",
        "tags": [
          "Tasks"
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "queued",
                "processing",
                "completed",
                "failed",
                "cancelled"
              ]
            },
            "description": "Фильтр по статусу задачи"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            },
            "description": "Количество задач на страницу"
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            },
            "description": "Смещение от начала списка"
          }
        ],
        "responses": {
          "200": {
            "description": "Список задач",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/tasks/{task_id}": {
      "get": {
        "summary": "Статус и прогресс задачи",
        "description": "Возвращает актуальный статус, прогресс выполнения (0-100%), ссылки для скачивания готового файла и метаданные синтеза.",
        "tags": [
          "Tasks"
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Статус задачи",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskStatusResponse"
                }
              }
            }
          },
          "404": {
            "description": "Задача не найдена",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/tasks/{task_id}/download": {
      "get": {
        "summary": "Скачивание готового MP3 аудио",
        "description": "Прямое скачивание синтезированного MP3-файла студийного качества (44.1 кГц, 128 кбит/с). Файл доступен в течение 5 часов с момента завершения синтеза.",
        "tags": [
          "Tasks"
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "MP3 аудиопоток",
            "content": {
              "audio/mpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "Файл не найден или срок хранения (5ч) истёк",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/tasks/{task_id}/cancel": {
      "post": {
        "summary": "Отмена задачи из очереди",
        "description": "Отменяет задачу, находящуюся в очереди или обработке. Зарезервированные символы мгновенно возвращаются на баланс суточной квоты. Повторные запросы, ошибки и отмены защищены от двойного списания символов.",
        "tags": [
          "Tasks"
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Задача успешно отменена",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelTaskResponse"
                }
              }
            }
          },
          "409": {
            "description": "Задача уже завершена и не может быть отменена",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/clones": {
      "post": {
        "summary": "Клонирование голоса",
        "description": "Создание персонального нейроклона по аудиообразцу длительностью от 5 до 30 секунд. После успешного создания голос автоматически публикуется в общем каталоге BlooTube Voice и становится доступен другим пользователям сервиса для синтеза.",
        "tags": [
          "Cloning"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "sample_file",
                  "name"
                ],
                "properties": {
                  "sample_file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Аудиозапись голоса (WAV, MP3, M4A, OGG от 5 до 30 сек, до 16 МБ)"
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 64,
                    "example": "Мой Студийный Голос"
                  },
                  "language": {
                    "type": "string",
                    "default": "ru",
                    "example": "ru"
                  },
                  "gender": {
                    "type": "string",
                    "enum": [
                      "male",
                      "female"
                    ],
                    "default": "female"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Клон создан и опубликован",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CloneItem"
                }
              }
            }
          },
          "400": {
            "description": "Превышен лимит слотов клонирования тарифа (PRO: 1 слот, ULTRA: 3 слота)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Список пользовательских клонов",
        "description": "Возвращает список созданных вами клонов и информацию о занятых слотах тарифа.",
        "tags": [
          "Cloning"
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CloneListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/clones/{voice_id}": {
      "delete": {
        "summary": "Удаление клонированного голоса",
        "description": "Удаляет ваш ранее созданный клон и освобождает слот тарифа.",
        "tags": [
          "Cloning"
        ],
        "parameters": [
          {
            "name": "voice_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Клон удалён, слот освобожден"
          },
          "404": {
            "description": "Клон не найден"
          }
        }
      }
    },
    "/pronunciation-dictionaries": {
      "post": {
        "summary": "Создание словаря произношения",
        "description": "Создает словарь фонетических подмен и правил транскрипции для терминов, аббревиатур и сложных слов.",
        "tags": [
          "Pronunciation"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "entries"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Медицинские термины"
                  },
                  "description": {
                    "type": "string",
                    "example": "Фонетические правила для фармакологии"
                  },
                  "entries": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/PronunciationEntry"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DictionaryResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Список словарей аккаунта",
        "description": "Возвращает список созданных словарей произношения.",
        "tags": [
          "Pronunciation"
        ],
        "responses": {
          "200": {
            "description": "Список словарей"
          }
        }
      }
    },
    "/pronunciation-dictionaries/{dict_id}": {
      "get": {
        "summary": "Получение словаря и всех записей",
        "description": "Возвращает метаданные словаря и полный список правил подмены.",
        "tags": [
          "Pronunciation"
        ],
        "parameters": [
          {
            "name": "dict_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Детальная информация о словаре"
          },
          "404": {
            "description": "Словарь не найден"
          }
        }
      },
      "patch": {
        "summary": "Обновление записей словаря",
        "description": "Позволяет обновить название, описание или состав записей словаря.",
        "tags": [
          "Pronunciation"
        ],
        "parameters": [
          {
            "name": "dict_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Словарь обновлен"
          }
        }
      },
      "delete": {
        "summary": "Удаление словаря",
        "description": "Удаляет словарь произношения.",
        "tags": [
          "Pronunciation"
        ],
        "parameters": [
          {
            "name": "dict_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Словарь удален"
          }
        }
      }
    }
  }
}