{
  "openapi": "3.0.3",
  "info": {
    "title": "Neo TTS Native API",
    "version": "1.0.0",
    "description": "API HTTP de síntesis C++17/Go. El acceso de automatizaciones externas requiere Bearer API key. Las cookies se reservan al Studio del mismo origen. Los enlaces de ouo.io no proporcionan una prueba verificable de visualización."
  },
  "servers": [
    {
      "url": "/",
      "description": "Mismo origen HTTPS"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAPIKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "neo_sk_..."
      }
    }
  },
  "paths": {
    "/api/v1/models": {
      "get": {
        "summary": "Catálogo público de modelos",
        "operationId": "get_api_v1_models",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        }
      }
    },
    "/api/v1/models/{id}": {
      "get": {
        "summary": "Ficha del modelo",
        "operationId": "get_api_v1_models_id",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/account/credits": {
      "get": {
        "summary": "Saldo disponible (microsegundos)",
        "operationId": "get_api_v1_account_credits",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        },
        "security": [
          {
            "BearerAPIKey": []
          }
        ]
      }
    },
    "/api/v1/generations": {
      "get": {
        "summary": "Últimas 40 generaciones de la cuenta",
        "operationId": "get_api_v1_generations",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        },
        "security": [
          {
            "BearerAPIKey": []
          }
        ]
      },
      "post": {
        "summary": "Generar audio con cuota",
        "operationId": "post_api_v1_generations",
        "responses": {
          "202": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        },
        "security": [
          {
            "BearerAPIKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "model": {
                    "type": "string",
                    "example": "claude_es_mx"
                  },
                  "text": {
                    "type": "string",
                    "maxLength": 16000,
                    "example": "Hola desde Neo TTS"
                  }
                },
                "required": [
                  "model",
                  "text"
                ]
              }
            }
          }
        },
        "description": "Una generación activa o en cola por cuenta/API key. Texto largo segmentado en unidades de hasta ~230 caracteres, con cola de prioridad ponderada y contabilidad por muestra."
      }
    },
    "/api/v1/generations/{id}": {
      "get": {
        "summary": "Estado y muestras confirmadas",
        "operationId": "get_api_v1_generations_id",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        },
        "security": [
          {
            "BearerAPIKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID aleatorio de la generación"
          }
        ]
      }
    },
    "/api/v1/generations/{id}/events": {
      "get": {
        "summary": "Eventos de progreso SSE",
        "operationId": "get_api_v1_generations_id_events",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        },
        "security": [
          {
            "BearerAPIKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID aleatorio de la generación"
          }
        ]
      }
    },
    "/api/v1/generations/{id}/audio": {
      "get": {
        "summary": "WAV parcial (soporta HTTP Range)",
        "operationId": "get_api_v1_generations_id_audio",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        },
        "security": [
          {
            "BearerAPIKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID aleatorio de la generación"
          }
        ]
      }
    },
    "/api/v1/generations/{id}/download": {
      "get": {
        "summary": "Descargar WAV final",
        "operationId": "get_api_v1_generations_id_download",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        },
        "security": [
          {
            "BearerAPIKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID aleatorio de la generación"
          }
        ]
      }
    },
    "/api/v1/generations/{id}/pcm": {
      "get": {
        "summary": "PCM16 mono progresivo",
        "operationId": "get_api_v1_generations_id_pcm",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        },
        "security": [
          {
            "BearerAPIKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID aleatorio de la generación"
          },
          {
            "name": "offset",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "frames",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 131072
            }
          }
        ]
      }
    },
    "/api/v1/generations/{id}/cancel": {
      "post": {
        "summary": "Detener sin perder audio",
        "operationId": "post_api_v1_generations_id_cancel",
        "responses": {
          "202": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        },
        "security": [
          {
            "BearerAPIKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ID aleatorio de la generación"
          }
        ]
      }
    },
    "/api/v1/rewards": {
      "get": {
        "summary": "Configuración pública de recompensas",
        "operationId": "get_api_v1_rewards",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        }
      }
    },
    "/api/v1/rewards/pending": {
      "get": {
        "summary": "Enlace pendiente (cookie invitado)",
        "operationId": "get_api_v1_rewards_pending",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        }
      }
    },
    "/api/v1/rewards/start": {
      "post": {
        "summary": "Crear o recuperar enlace promocional",
        "operationId": "post_api_v1_rewards_start",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        }
      }
    },
    "/api/v1/session": {
      "get": {
        "summary": "Estado de sesión de navegador",
        "operationId": "get_api_v1_session",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        }
      },
      "post": {
        "summary": "Crear cookie de invitado",
        "operationId": "post_api_v1_session",
        "responses": {
          "201": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        }
      }
    },
    "/api/v1/browser/login": {
      "post": {
        "summary": "Conectar API key al Studio mediante cookie HttpOnly",
        "operationId": "post_api_v1_browser_login",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "key": {
                    "type": "string"
                  }
                },
                "required": [
                  "key"
                ]
              }
            }
          }
        }
      }
    },
    "/api/v1/browser/logout": {
      "post": {
        "summary": "Desconectar la clave del navegador",
        "operationId": "post_api_v1_browser_logout",
        "responses": {
          "200": {
            "description": "Respuesta correcta"
          },
          "400": {
            "description": "Solicitud inválida"
          },
          "401": {
            "description": "Autenticación requerida"
          },
          "403": {
            "description": "Acceso restringido"
          },
          "429": {
            "description": "Límite de solicitudes"
          }
        }
      }
    },
    "/api/v1/generations/{id}/segments": {
      "get": {
        "summary": "Progreso y rangos de los fragmentos naturales",
        "security": [
          {
            "BearerAPIKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Correcto"
          },
          "401": {
            "description": "Sin autorización"
          },
          "404": {
            "description": "No disponible"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/generations/{id}/waveform": {
      "get": {
        "summary": "Picos normalizados (24–512 bins) para forma de onda",
        "security": [
          {
            "BearerAPIKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Correcto"
          },
          "401": {
            "description": "Sin autorización"
          },
          "404": {
            "description": "No disponible"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bins",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 24,
              "maximum": 512
            }
          }
        ]
      }
    },
    "/api/v1/generations/{id}/clip": {
      "get": {
        "summary": "Descarga WAV de un rango autenticado de hasta 180 segundos",
        "security": [
          {
            "BearerAPIKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Correcto"
          },
          "401": {
            "description": "Sin autorización"
          },
          "404": {
            "description": "No disponible"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "end",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ]
      }
    },
    "/api/v1/models/{id}/demo": {
      "get": {
        "summary": "Demo WAV pública de la voz",
        "security": [],
        "responses": {
          "200": {
            "description": "Correcto"
          },
          "401": {
            "description": "Sin autorización"
          },
          "404": {
            "description": "No disponible"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/v1/generations/{id}/metrics": {
      "get": {
        "summary": "TTFA, cola, duración de inferencia, factor de tiempo real y reutilización del motor",
        "security": [
          {
            "BearerAPIKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Mediciones reales de la generación"
          },
          "401": {
            "description": "Clave requerida"
          },
          "404": {
            "description": "Generación ajena"
          }
        }
      }
    }
  }
}