{
  "openapi": "3.1.0",
  "info": {
    "title": "AudioWorld TTS API",
    "version": "1.0.0-beta",
    "description": "OpenAI SDK-compatible request format for AudioWorld fixed synthetic preset voices. This is an independent AudioWorld service, not an OpenAI service."
  },
  "servers": [
    { "url": "https://play.audioworld.ai/v1" }
  ],
  "paths": {
    "/audio/speech": {
      "post": {
        "operationId": "createSpeech",
        "summary": "Generate speech from text",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": { "type": "string", "maxLength": 255 },
            "description": "Reuse the same UUID when retrying one logical request."
          },
          {
            "in": "header",
            "name": "Prefer",
            "required": false,
            "schema": { "type": "string", "enum": ["respond-async"] },
            "description": "Return a 202 job resource instead of waiting for the WAV response."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SpeechRequest" },
              "examples": {
                "korean": {
                  "value": {
                    "model": "audioworld-tts-1",
                    "voice": "asmr_male_01",
                    "input": "오늘 주문하신 상품은 오후 3시 30분에 도착합니다.",
                    "response_format": "wav"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated WAV audio",
            "headers": {
              "x-request-id": { "schema": { "type": "string" } }
            },
            "content": { "audio/wav": { "schema": { "type": "string", "contentEncoding": "binary" } } }
          },
          "202": {
            "description": "Asynchronous job accepted",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJob" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "402": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "500": { "$ref": "#/components/responses/Error" },
          "504": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/audio/speech/{request_id}": {
      "get": {
        "operationId": "getSpeechStatus",
        "summary": "Get asynchronous speech status",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/RequestId" }],
        "responses": {
          "200": { "description": "Current job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJob" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/audio/speech/{request_id}/content": {
      "get": {
        "operationId": "getSpeechContent",
        "summary": "Download completed asynchronous speech",
        "security": [{ "bearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/RequestId" }],
        "responses": {
          "200": { "description": "Generated WAV audio", "content": { "audio/wav": { "schema": { "type": "string", "contentEncoding": "binary" } } } },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" },
          "410": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "AudioWorld API key" }
    },
    "parameters": {
      "RequestId": { "in": "path", "name": "request_id", "required": true, "schema": { "type": "string" } }
    },
    "schemas": {
      "SpeechRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["model", "input", "voice"],
        "properties": {
          "model": { "type": "string", "enum": ["audioworld-tts-1", "audioworld-tts-1-2026-08-14"] },
          "input": { "type": "string", "minLength": 1 },
          "voice": {
            "oneOf": [
              { "$ref": "#/components/schemas/VoiceId" },
              { "type": "object", "required": ["id"], "properties": { "id": { "$ref": "#/components/schemas/VoiceId" } } }
            ]
          },
          "response_format": { "type": "string", "enum": ["wav"], "default": "wav" },
          "speed": { "type": "number", "enum": [1], "default": 1 },
          "stream_format": { "type": "string", "enum": ["audio"], "default": "audio" },
          "language": { "type": "string", "enum": ["Auto", "Korean", "English", "Chinese", "Japanese", "French", "German", "Spanish", "Portuguese", "Russian", "Italian"], "default": "Auto" }
        }
      },
      "VoiceId": {
        "type": "string",
        "enum": ["seungyeon_female_01", "asmr_male_01", "Sohee", "Serena", "Vivian", "Aiden", "Dylan", "Eric", "Ryan", "Ono_Anna", "Uncle_Fu", "byungchul", "dohyun", "hajun", "hayoon", "jian", "jungwoo", "junseo", "mansu", "minji", "seoa", "seoyeon", "siwoo", "sunja", "youngsoon"]
      },
      "AsyncJob": {
        "type": "object",
        "required": ["request_id", "status"],
        "properties": {
          "request_id": { "type": "string" },
          "status": { "type": "string", "enum": ["queued", "processing", "completed", "failed", "refunded", "canceled"] },
          "status_url": { "type": "string", "format": "uri" },
          "audio_url": { "type": ["string", "null"], "format": "uri" },
          "expires_at": { "type": ["integer", "null"] }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message", "type", "code"],
            "properties": {
              "message": { "type": "string" },
              "type": { "type": "string" },
              "param": { "type": ["string", "null"] },
              "code": { "type": "string" }
            }
          }
        }
      }
    },
    "responses": {
      "Error": { "description": "API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}