{
  "openapi": "3.0.3",
  "info": {
    "title": "OmniTranslate API",
    "description": "AI-Powered Translation, ASR, TTS & Chat API. 支持网页/插件翻译、语音识别、快速/高质量语音合成、AI 对话与实时语音翻译。\n\n**认证和额度**: 匿名用户按 IP/浏览器指纹限制次数；W-ID 登录用户按 user_id 识别，登录后不限制次数。服务端调用可使用 `Authorization: Bearer` 或 `X-API-Key`。\n\n**TTS 质量和格式**: `/tts` 支持 `quality=fast|high`。fast 使用 Kokoro/MeloTTS 低延迟路线；high 使用 IndexTTS 高质量路线。默认返回压缩 MP3；需要旧版无压缩音频时传 `format=wav`。`/tts/reference` 支持上传说话人参考音频和情绪参考音频。",
    "version": "3.0.0",
    "contact": {
      "name": "Obscura Lab",
      "url": "https://translate.myfastools.com"
    }
  },
  "servers": [
    {
      "url": "https://translate.myfastools.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/translate": {
      "post": {
        "summary": "单条翻译",
        "description": "将文本翻译为目标语言，支持 5 种翻译风格",
        "tags": ["翻译"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TranslateRequest" },
              "example": {
                "content": "Hello, how are you?",
                "target_language": "中文",
                "style": "casual"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "翻译成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TranslateResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "502": { "$ref": "#/components/responses/BackendError" }
        }
      }
    },
    "/translate/batch": {
      "post": {
        "summary": "批量翻译",
        "description": "批量翻译多条文本。当前接口接收 sentences 数组、统一目标语言和可选 source_url/style。",
        "tags": ["翻译"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BatchTranslateRequest" },
              "example": {
                "sentences": ["Hello", "Good morning"],
                "target_language": "中文",
                "style": "casual",
                "source_url": "https://example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "批量翻译成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BatchTranslateResponse" }
              }
            }
          }
        }
      }
    },
    "/web/translate": {
      "post": {
        "summary": "网页翻译",
        "description": "网页/浏览器插件翻译接口。请求体接收 sentences 数组，额外记录 IP/UA 审计日志。",
        "tags": ["翻译"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WebTranslateRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "翻译成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TranslateResponse" }
              }
            }
          }
        }
      }
    },
    "/asr": {
      "post": {
        "summary": "语音识别 (ASR)",
        "description": "语音转文字，自动检测语言。上传 WAV 音频文件 (16kHz PCM16 推荐)。",
        "tags": ["语音"],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["audio"],
                "properties": {
                  "audio": {
                    "type": "string",
                    "format": "binary",
                    "description": "WAV 音频文件"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "识别成功",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ASRResponse" }
              }
            }
          }
        }
      }
    },
    "/tts": {
      "post": {
        "summary": "语音合成 (TTS)",
        "description": "文字转语音。`quality=fast` 自动路由: 日语/韩语 → MeloTTS, 其余 → Kokoro-82M。`quality=high` 路由到 IndexTTS 高质量路线。默认 `format=mp3` 返回压缩 MP3；传 `format=wav` 可返回未压缩 WAV。",
        "tags": ["语音"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TTSRequest" },
              "example": { "text": "你好世界", "language": "中文", "quality": "fast", "format": "mp3" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "音频流，默认 MP3；显式 format=wav 时返回 WAV",
            "headers": {
              "X-TTS-Cache": {
                "schema": { "type": "string", "enum": ["HIT", "MISS"] },
                "description": "缓存状态"
              },
              "X-TTS-Quality": {
                "schema": { "type": "string", "enum": ["HIGH", "FAST"] },
                "description": "音频质量等级"
              },
              "X-TTS-Format": {
                "schema": { "type": "string", "enum": ["mp3", "wav"] },
                "description": "输出音频格式"
              }
            },
            "content": {
              "audio/mpeg": {
                "schema": { "type": "string", "format": "binary" }
              },
              "audio/wav": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          }
        }
      }
    },
    "/tts/reference": {
      "post": {
        "summary": "参考音频高质量 TTS",
        "description": "IndexTTS 高质量语音合成。必须上传 speaker_audio/reference_audio，可选 emotion_audio/style_audio、emotion_alpha 和 format。默认 format=mp3；传 format=wav 可返回未压缩 WAV。",
        "tags": ["语音"],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["text", "speaker_audio"],
                "properties": {
                  "text": { "type": "string", "maxLength": 5000 },
                  "language": { "type": "string", "default": "中文" },
                  "speaker_audio": { "type": "string", "format": "binary", "description": "说话人/音色参考音频" },
                  "reference_audio": { "type": "string", "format": "binary", "description": "speaker_audio 的兼容字段名" },
                  "emotion_audio": { "type": "string", "format": "binary", "description": "情绪/风格参考音频" },
                  "emotion_alpha": { "type": "number", "default": 0.8, "minimum": 0, "maximum": 1 },
                  "format": { "type": "string", "enum": ["mp3", "wav"], "default": "mp3" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "音频流，默认 MP3；显式 format=wav 时返回 WAV",
            "headers": {
              "X-TTS-Quality": {
                "schema": { "type": "string", "enum": ["HIGH"] },
                "description": "音频质量等级"
              },
              "X-TTS-Backend": {
                "schema": { "type": "string", "enum": ["IndexTTS"] },
                "description": "TTS 后端"
              },
              "X-TTS-Format": {
                "schema": { "type": "string", "enum": ["mp3", "wav"] },
                "description": "输出音频格式"
              }
            },
            "content": {
              "audio/mpeg": {
                "schema": { "type": "string", "format": "binary" }
              },
              "audio/wav": {
                "schema": { "type": "string", "format": "binary" }
              }
            }
          }
        }
      }
    },
    "/chat": {
      "post": {
        "summary": "AI 对话",
        "description": "多轮 AI 对话 (Qwen3-8B-AWQ)。自动跟随用户语言回复。",
        "tags": ["AI"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatRequest" },
              "example": { "message": "안녕하세요!", "history": [] }
            }
          }
        },
        "responses": {
          "200": {
            "description": "对话回复",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatResponse" }
              }
            }
          }
        }
      }
    },
    "/voice-translate": {
      "post": {
        "summary": "语音翻译",
        "description": "一站式: 语音 → 识别 → 翻译 → 语音合成",
        "tags": ["语音"],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["audio"],
                "properties": {
                  "audio": { "type": "string", "format": "binary" },
                  "target_language": { "type": "string", "default": "English" },
                  "style": { "type": "string", "default": "default" },
                  "output": { "type": "string", "enum": ["json", "audio"], "default": "json" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "翻译结果 + 音频",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VoiceTranslateResponse" }
              }
            }
          }
        }
      }
    },
    "/report": {
      "post": {
        "summary": "提交翻译反馈",
        "tags": ["报告"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ReportRequest" }
            }
          }
        },
        "responses": { "200": { "description": "提交成功" } }
      }
    },
    "/reports": {
      "get": {
        "summary": "查询反馈列表",
        "description": "返回最近 50 条反馈记录",
        "tags": ["报告"],
        "responses": { "200": { "description": "反馈列表" } }
      }
    },
    "/report/page": {
      "post": {
        "summary": "页面翻译统计",
        "tags": ["报告"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PageReportRequest" }
            }
          }
        },
        "responses": { "200": { "description": "统计成功" } }
      }
    },
    "/health": {
      "get": {
        "summary": "健康检查",
        "tags": ["系统"],
        "responses": {
          "200": {
            "description": "服务健康状态",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "TranslateRequest": {
        "type": "object",
        "required": ["content", "target_language"],
        "properties": {
          "content": { "type": "string", "maxLength": 5000, "description": "源文本" },
          "target_language": { "type": "string", "enum": ["中文", "English", "日本語", "한국어", "Français", "Español", "Deutsch", "Русский", "Português", "العربية"], "description": "目标语言" },
          "style": { "type": "string", "enum": ["casual", "formal", "literary", "subtitle", "technical"], "default": "casual", "description": "翻译风格" }
        }
      },
      "TranslateResponse": {
        "type": "object",
        "properties": {
          "translated": { "type": "string" },
          "cached": { "type": "boolean" },
          "source": { "type": "string" },
          "target_language": { "type": "string" },
          "model_version": { "type": "string" }
        }
      },
      "BatchTranslateRequest": {
        "type": "object",
        "required": ["items"],
        "properties": {
          "sentences": { "type": "array", "maxItems": 50, "items": { "type": "string" } },
          "target_language": { "type": "string" },
          "source_url": { "type": "string" },
          "style": { "type": "string", "default": "casual" }
        }
      },
      "BatchTranslateResponse": {
        "type": "object",
        "properties": {
          "translations": { "type": "array", "items": { "type": "string" } }
        }
      },
      "WebTranslateRequest": {
        "type": "object",
        "required": ["sentences", "target_language"],
        "properties": {
          "sentences": { "type": "array", "items": { "type": "string" } },
          "target_language": { "type": "string" },
          "style": { "type": "string" }
        }
      },
      "TTSRequest": {
        "type": "object",
        "required": ["text"],
        "properties": {
          "text": { "type": "string", "maxLength": 5000 },
          "language": { "type": "string", "default": "中文" },
          "quality": { "type": "string", "enum": ["fast", "high"], "default": "fast" },
          "format": { "type": "string", "enum": ["mp3", "wav"], "default": "mp3" }
        }
      },
      "ASRResponse": {
        "type": "object",
        "properties": {
          "text": { "type": "string" },
          "language": { "type": "string" },
          "duration_ms": { "type": "integer" }
        }
      },
      "ChatRequest": {
        "type": "object",
        "required": ["message"],
        "properties": {
          "message": { "type": "string", "maxLength": 4000 },
          "history": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } } } }
        }
      },
      "ChatResponse": {
        "type": "object",
        "properties": {
          "reply": { "type": "string" },
          "model": { "type": "string" },
          "latency_ms": { "type": "integer" }
        }
      },
      "VoiceTranslateResponse": {
        "type": "object",
        "properties": {
          "recognized_text": { "type": "string" },
          "source_language": { "type": "string" },
          "translated_text": { "type": "string" },
          "target_language": { "type": "string" },
          "asr_ms": { "type": "integer" },
          "translate_ms": { "type": "integer" },
          "tts_ms": { "type": "integer" },
          "total_ms": { "type": "integer" }
        }
      },
      "ReportRequest": {
        "type": "object",
        "properties": {
          "url": { "type": "string" },
          "error_message": { "type": "string" },
          "source_text": { "type": "string" },
          "translated_text": { "type": "string" },
          "report_type": { "type": "string" }
        }
      },
      "PageReportRequest": {
        "type": "object",
        "properties": {
          "source_url": { "type": "string" },
          "target_language": { "type": "string" },
          "sentence_count": { "type": "integer" },
          "cache_hits": { "type": "integer" }
        }
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "string" },
          "model_version": { "type": "string" },
          "total_translations": { "type": "integer" },
          "cache_hit_rate_percent": { "type": "number" },
          "avg_response_ms": { "type": "number" }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "请求参数错误",
        "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } }
      },
      "BackendError": {
        "description": "后端 AI 服务不可用",
        "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } }
      }
    }
  }
}