local-coze 0.0.1__py3-none-any.whl

local_coze/cli/voice.py

@@ -0,0 +1,351 @@
+import base64
+import json
+import os
+import time
+from typing import Optional
+
+import click
+from coze_coding_utils.runtime_ctx.context import new_context
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich.table import Table
+
+from ..core.config import Config
+from ..voice.asr import ASRClient
+from ..voice.models import TTSConfig
+from ..voice.tts import TTSClient
+from .constants import RUN_MODE_HEADER, RUN_MODE_TEST
+
+console = Console()
+
+COMMON_SPEAKERS = {
+    "zh_female_xueayi_saturn_bigtts": "儿童绘本 (有声阅读)",
+    "zh_female_vv_uranus_bigtts": "vivi (通用场景, 中英)",
+    "zh_male_dayi_saturn_bigtts": "大壹 (视频配音)",
+    "zh_female_mizai_saturn_bigtts": "黑猫侦探社咪仔 (视频配音)",
+    "zh_female_jitangnv_saturn_bigtts": "鸡汤女 (视频配音)",
+    "zh_female_meilinvyou_saturn_bigtts": "魅力女友 (视频配音)",
+    "zh_female_santongyongns_saturn_bigtts": "流畅女声 (视频配音)",
+    "zh_male_ruyayichen_saturn_bigtts": "儒雅逸辰 (视频配音)",
+    "zh_female_xiaohe_uranus_bigtts": "小何 (通用场景, 默认)",
+    "zh_male_m191_uranus_bigtts": "云舟 (通用场景)",
+    "zh_male_taocheng_uranus_bigtts": "小天 (通用场景)",
+    "saturn_zh_female_keainvsheng_tob": "可爱女生 (角色扮演)",
+    "saturn_zh_female_tiaopigongzhu_tob": "调皮公主 (角色扮演)",
+    "saturn_zh_male_shuanglangshaonian_tob": "爽朗少年 (角色扮演)",
+    "saturn_zh_male_tiancaitongzhuo_tob": "天才同桌 (角色扮演)",
+    "saturn_zh_female_cancan_tob": "知性灿灿 (角色扮演)",
+}
+
+
+@click.command()
+@click.argument("text")
+@click.option(
+    "--output", "-o", required=True, type=click.Path(), help="输出音频文件路径"
+)
+@click.option("--uid", "-u", default="cli_user", help="用户唯一标识")
+@click.option("--speaker", "-s", default=TTSConfig.DEFAULT_SPEAKER, help="音色选择")
+@click.option(
+    "--format",
+    "-f",
+    type=click.Choice(["mp3", "pcm", "ogg_opus"]),
+    default="mp3",
+    help="音频格式",
+)
+@click.option(
+    "--sample-rate",
+    type=int,
+    default=24000,
+    help="采样率 (8000/16000/22050/24000/32000/44100/48000)",
+)
+@click.option("--speech-rate", type=int, default=0, help="语速 (-50 到 100)")
+@click.option("--loudness-rate", type=int, default=0, help="音量 (-50 到 100)")
+@click.option("--ssml", is_flag=True, help="使用 SSML 格式")
+@click.option("--mock", is_flag=True, help="使用 mock 模式（测试运行）")
+@click.option(
+    "--header",
+    "-H",
+    multiple=True,
+    help="自定义 HTTP 请求头 (格式: 'Key: Value' 或 'Key=Value'，可多次使用)",
+)
+@click.option("--verbose", "-v", is_flag=True, help="显示详细的 HTTP 请求日志")
+def tts(
+    text,
+    output,
+    uid,
+    speaker,
+    format,
+    sample_rate,
+    speech_rate,
+    loudness_rate,
+    ssml,
+    mock,
+    header,
+    verbose,
+):
+    """语音合成 (Text-to-Speech)
+
+    将文本转换为语音音频文件。
+
+    音色列表 (按场景分类):
+
+    有声阅读:
+      - zh_female_xueayi_saturn_bigtts (儿童绘本)
+
+    通用场景:
+      - zh_female_xiaohe_uranus_bigtts (小何, 默认)
+      - zh_female_vv_uranus_bigtts (vivi, 支持中英)
+      - zh_male_m191_uranus_bigtts (云舟)
+      - zh_male_taocheng_uranus_bigtts (小天)
+
+    视频配音:
+      - zh_male_dayi_saturn_bigtts (大壹)
+      - zh_female_mizai_saturn_bigtts (黑猫侦探社咪仔)
+      - zh_female_jitangnv_saturn_bigtts (鸡汤女)
+      - zh_female_meilinvyou_saturn_bigtts (魅力女友)
+      - zh_female_santongyongns_saturn_bigtts (流畅女声)
+      - zh_male_ruyayichen_saturn_bigtts (儒雅逸辰)
+
+    角色扮演:
+      - saturn_zh_female_keainvsheng_tob (可爱女生)
+      - saturn_zh_female_tiaopigongzhu_tob (调皮公主)
+      - saturn_zh_male_shuanglangshaonian_tob (爽朗少年)
+      - saturn_zh_male_tiancaitongzhuo_tob (天才同桌)
+      - saturn_zh_female_cancan_tob (知性灿灿)
+
+    示例:
+      coze-coding-ai tts "你好,欢迎使用" -o hello.mp3
+      coze-coding-ai tts "测试视频配音" -o test.mp3 -s zh_male_dayi_saturn_bigtts
+      coze-coding-ai tts "儿童故事" -o story.mp3 -s zh_female_xueayi_saturn_bigtts --speech-rate 20
+    """
+    try:
+        from .utils import parse_headers
+
+        config = Config()
+
+        ctx = None
+        custom_headers = parse_headers(header) or {}
+
+        if mock:
+            ctx = new_context(method="tts.generate", headers=custom_headers)
+            custom_headers[RUN_MODE_HEADER] = RUN_MODE_TEST
+            console.print("[yellow]🧪 Mock 模式已启用（测试运行）[/yellow]")
+
+        client = TTSClient(
+            config, ctx=ctx, custom_headers=custom_headers, verbose=verbose
+        )
+
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            task = progress.add_task("[cyan]正在合成语音...", total=None)
+
+            if ssml:
+                audio_url, audio_size = client.synthesize(
+                    uid=uid,
+                    ssml=text,
+                    speaker=speaker,
+                    audio_format=format,
+                    sample_rate=sample_rate,
+                    speech_rate=speech_rate,
+                    loudness_rate=loudness_rate,
+                )
+            else:
+                audio_url, audio_size = client.synthesize(
+                    uid=uid,
+                    text=text,
+                    speaker=speaker,
+                    audio_format=format,
+                    sample_rate=sample_rate,
+                    speech_rate=speech_rate,
+                    loudness_rate=loudness_rate,
+                )
+
+            progress.update(task, description="[green]✓ 语音合成完成")
+
+        os.makedirs(
+            (
+                os.path.dirname(os.path.abspath(output))
+                if os.path.dirname(output)
+                else "."
+            ),
+            exist_ok=True,
+        )
+
+        if audio_url:
+            import requests
+
+            response = requests.get(audio_url)
+            response.raise_for_status()
+            with open(output, "wb") as f:
+                f.write(response.content)
+            file_size = len(response.content)
+        else:
+            file_size = audio_size
+
+        table = Table(show_header=False, box=None, padding=(0, 2))
+        table.add_column("Key", style="cyan")
+        table.add_column("Value", style="white", no_wrap=False, overflow="fold")
+
+        display_text = text[:50] + "..." if len(text) > 50 else text
+        table.add_row("文本", display_text)
+        table.add_row("音色", COMMON_SPEAKERS.get(speaker, speaker))
+        table.add_row("格式", format.upper())
+        table.add_row("采样率", f"{sample_rate} Hz")
+        if speech_rate != 0:
+            table.add_row("语速", f"{speech_rate:+d}")
+        if loudness_rate != 0:
+            table.add_row("音量", f"{loudness_rate:+d}")
+        table.add_row("文件", output)
+        table.add_row("大小", f"{file_size / 1024:.1f} KB")
+        if audio_url:
+            table.add_row("URL", audio_url)
+
+        console.print()
+        console.print(
+            Panel(
+                table,
+                title="[bold green]语音合成完成[/bold green]",
+                border_style="green",
+            )
+        )
+
+    except Exception as e:
+        console.print(f"[red]✗ 错误: {str(e)}[/red]")
+        raise click.Abort()
+
+
+@click.command()
+@click.argument("audio")
+@click.option("--uid", "-u", default="cli_user", help="用户唯一标识")
+@click.option("--output", "-o", type=click.Path(), help="输出文本文件路径")
+@click.option(
+    "--format",
+    "-f",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    help="输出格式",
+)
+@click.option("--base64", is_flag=True, help="将本地文件转为 base64 上传")
+@click.option("--mock", is_flag=True, help="使用 mock 模式（测试运行）")
+@click.option(
+    "--header",
+    "-H",
+    multiple=True,
+    help="自定义 HTTP 请求头 (格式: 'Key: Value' 或 'Key=Value'，可多次使用)",
+)
+@click.option("--verbose", "-v", is_flag=True, help="显示详细的 HTTP 请求日志")
+def asr(audio, uid, output, format, base64, mock, header, verbose):
+    """语音识别 (Automatic Speech Recognition)
+
+    将语音音频转换为文本。
+
+    音频要求:
+      - 音频时长 ≤ 2小时
+      - 音频大小 ≤ 100MB
+      - 支持编码: WAV/MP3/OGG OPUS
+
+    支持:
+      - 本地音频文件
+      - 音频 URL
+      - Base64 编码上传
+
+    示例:
+      coze-coding-ai asr ./audio.mp3
+      coze-coding-ai asr https://example.com/audio.mp3
+      coze-coding-ai asr ./audio.mp3 -o result.txt
+      coze-coding-ai asr ./audio.mp3 -f json
+      coze-coding-ai asr audio.mp3 --base64 --output result.txt
+    """
+    try:
+        from .utils import parse_headers
+
+        config = Config()
+
+        ctx = None
+        custom_headers = parse_headers(header) or {}
+
+        if mock:
+            ctx = new_context(method="asr.recognize", headers=custom_headers)
+            custom_headers[RUN_MODE_HEADER] = RUN_MODE_TEST
+            console.print("[yellow]🧪 Mock 模式已启用（测试运行）[/yellow]")
+
+        client = ASRClient(
+            config, ctx=ctx, custom_headers=custom_headers, verbose=verbose
+        )
+
+        audio_url = None
+        audio_base64 = None
+
+        if audio.startswith(("http://", "https://")):
+            audio_url = audio
+            console.print(f"[cyan]正在识别 URL 音频:[/cyan] {audio}")
+        else:
+            if not os.path.exists(audio):
+                raise FileNotFoundError(f"音频文件不存在: {audio}")
+
+            if base64:
+                import base64 as b64_module
+
+                console.print(f"[cyan]正在读取并编码音频文件:[/cyan] {audio}")
+                with open(audio, "rb") as f:
+                    audio_data = f.read()
+                    audio_base64 = b64_module.b64encode(audio_data).decode("utf-8")
+            else:
+                raise ValueError(
+                    "本地文件需要先上传到可访问的 URL,或使用 --base64 选项"
+                )
+
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            task = progress.add_task("[cyan]正在识别语音...", total=None)
+
+            text, data = client.recognize(
+                uid=uid, url=audio_url, base64_data=audio_base64
+            )
+
+            progress.update(task, description="[green]✓ 识别完成")
+
+        console.print()
+
+        if format == "json":
+            result = {
+                "text": text,
+                "duration": data.get("result", {}).get("duration"),
+                "utterances": data.get("result", {}).get("utterances", []),
+            }
+
+            if output:
+                with open(output, "w", encoding="utf-8") as f:
+                    json.dump(result, f, ensure_ascii=False, indent=2)
+                console.print(f"[green]✓[/green] 结果已保存到: {output}")
+            else:
+                console.print_json(data=result)
+        else:
+            console.print(
+                Panel(
+                    text,
+                    title="[bold green]识别结果[/bold green]",
+                    border_style="green",
+                    padding=(1, 2),
+                )
+            )
+
+            duration = data.get("result", {}).get("duration")
+            if duration:
+                console.print(f"\n[dim]音频时长: {duration / 1000:.1f} 秒[/dim]")
+
+            if output:
+                with open(output, "w", encoding="utf-8") as f:
+                    f.write(text)
+                console.print(f"[green]✓[/green] 结果已保存到: {output}")
+
+    except Exception as e:
+        console.print(f"[red]✗ 错误: {str(e)}[/red]")
+        raise click.Abort()

local_coze/core/__init__.py

@@ -0,0 +1,25 @@
+from .client import BaseClient
+from .config import Config
+from .exceptions import (
+    CozeSDKError,
+    ConfigurationError,
+    APIError,
+    NetworkError,
+    ValidationError
+)
+
+try:
+    from .. import __version__
+except ImportError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "BaseClient",
+    "Config",
+    "CozeSDKError",
+    "ConfigurationError",
+    "APIError",
+    "NetworkError",
+    "ValidationError",
+    "__version__",
+]

local_coze/core/client.py

@@ -0,0 +1,253 @@
+import json
+import time
+from typing import Dict, Optional
+
+import requests
+from coze_coding_utils.runtime_ctx.context import Context, default_headers
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+
+from .config import Config
+from .exceptions import APIError, NetworkError
+
+console = Console()
+
+
+class BaseClient:
+    def __init__(
+        self,
+        config: Optional[Config] = None,
+        ctx: Optional[Context] = None,
+        custom_headers: Optional[Dict[str, str]] = None,
+        verbose: bool = False,
+    ):
+        if config is None:
+            config = Config()
+        self.config = config
+        self.ctx = ctx
+        self.custom_headers = custom_headers or {}
+        self.verbose = verbose
+
+    def _request(
+        self, method: str, url: str, headers: Optional[Dict[str, str]] = None, **kwargs
+    ) -> dict:
+        request_headers = {}
+
+        if self.ctx is not None:
+            ctx_headers = default_headers(self.ctx)
+            request_headers.update(ctx_headers)
+
+        if self.custom_headers:
+            request_headers.update(self.custom_headers)
+
+        config_headers = self.config.get_headers(headers)
+        request_headers.update(config_headers)
+
+        response = self._make_request(
+            method=method, url=url, headers=request_headers, **kwargs
+        )
+        return self._handle_response(response)
+
+    def _request_with_response(
+        self, method: str, url: str, headers: Optional[Dict[str, str]] = None, **kwargs
+    ) -> requests.Response:
+        request_headers = {}
+
+        if self.ctx is not None:
+            ctx_headers = default_headers(self.ctx)
+            request_headers.update(ctx_headers)
+
+        if self.custom_headers:
+            request_headers.update(self.custom_headers)
+
+        config_headers = self.config.get_headers(headers)
+        request_headers.update(config_headers)
+
+        response = self._make_request(
+            method=method, url=url, headers=request_headers, **kwargs
+        )
+        return response
+
+    def _request_stream(
+        self, method: str, url: str, headers: Optional[Dict[str, str]] = None, **kwargs
+    ) -> requests.Response:
+        request_headers = {}
+
+        if self.ctx is not None:
+            ctx_headers = default_headers(self.ctx)
+            request_headers.update(ctx_headers)
+
+        if self.custom_headers:
+            request_headers.update(self.custom_headers)
+
+        config_headers = self.config.get_headers(headers)
+        request_headers.update(config_headers)
+
+        kwargs["stream"] = True
+        return self._make_request(
+            method=method, url=url, headers=request_headers, **kwargs
+        )
+
+    def _sanitize_headers(self, headers: Dict[str, str]) -> Dict[str, str]:
+        sanitized = headers.copy()
+        if "Authorization" in sanitized:
+            token = sanitized["Authorization"]
+            if token.startswith("Bearer "):
+                token = token[7:]
+                if len(token) > 16:
+                    sanitized["Authorization"] = f"Bearer {token[:8]}...{token[-4:]}"
+                else:
+                    sanitized["Authorization"] = "Bearer ****"
+        return sanitized
+
+    def _log_request(self, method: str, url: str, **kwargs):
+        if not self.verbose:
+            return
+
+        parts = []
+        parts.append(f"[bold cyan]{method}[/bold cyan] {url}\n")
+
+        headers = kwargs.get("headers", {})
+        sanitized_headers = self._sanitize_headers(headers)
+        if sanitized_headers:
+            parts.append("[bold]Headers:[/bold]")
+            for key, value in sanitized_headers.items():
+                parts.append(f"  {key}: {value}")
+            parts.append("")
+
+        if "json" in kwargs and kwargs["json"]:
+            parts.append("[bold]Body:[/bold]")
+            try:
+                json_str = json.dumps(kwargs["json"], ensure_ascii=False, indent=2)
+                parts.append("")
+            except Exception:
+                json_str = str(kwargs["json"])
+                parts.append("")
+
+        content = "\n".join(parts)
+        console.print(
+            Panel(
+                content,
+                title="[bold green]HTTP Request[/bold green]",
+                border_style="green",
+            )
+        )
+
+        if "json" in kwargs and kwargs["json"]:
+            try:
+                json_str = json.dumps(kwargs["json"], ensure_ascii=False, indent=2)
+                console.print(
+                    Syntax(json_str, "json", theme="monokai", line_numbers=False)
+                )
+                console.print()
+            except Exception:
+                pass
+
+    def _log_response(self, response: requests.Response, is_stream: bool = False):
+        if not self.verbose:
+            return
+
+        parts = []
+        parts.append(f"[bold]Status:[/bold] {response.status_code} {response.reason}\n")
+
+        response_headers = dict(response.headers)
+        sanitized_response_headers = self._sanitize_headers(response_headers)
+        if sanitized_response_headers:
+            parts.append("[bold]Response Headers:[/bold]")
+            for key, value in sanitized_response_headers.items():
+                parts.append(f"  {key}: {value}")
+            parts.append("")
+
+        if is_stream:
+            parts.append("[yellow]⚡ Streaming response - body not shown[/yellow]")
+            content = "\n".join(parts)
+            console.print(
+                Panel(
+                    content,
+                    title="[bold blue]HTTP Response[/bold blue]",
+                    border_style="blue",
+                )
+            )
+            console.print()
+            return
+
+        parts.append("[bold]Body:[/bold]")
+
+        content = "\n".join(parts)
+        console.print(
+            Panel(
+                content,
+                title="[bold blue]HTTP Response[/bold blue]",
+                border_style="blue",
+            )
+        )
+
+        try:
+            response_data = response.json()
+            json_str = json.dumps(response_data, ensure_ascii=False, indent=2)
+            if len(json_str) > 2000:
+                json_str = json_str[:2000] + "\n... (truncated)"
+            console.print(Syntax(json_str, "json", theme="monokai", line_numbers=False))
+        except Exception:
+            body_text = response.text[:500]
+            if len(response.text) > 500:
+                body_text += "... (truncated)"
+            console.print(f"  {body_text}")
+
+        console.print()
+
+    def _make_request(self, method: str, url: str, **kwargs) -> requests.Response:
+        last_error = None
+        is_stream = kwargs.get("stream", False)
+
+        for attempt in range(self.config.retry_times):
+            try:
+                if attempt == 0:
+                    self._log_request(method, url, **kwargs)
+
+                response = requests.request(
+                    method=method, url=url, timeout=self.config.timeout, **kwargs
+                )
+
+                if attempt == 0:
+                    self._log_response(response, is_stream=is_stream)
+
+                return response
+
+            except requests.exceptions.RequestException as e:
+                last_error = NetworkError(str(e), e)
+                if attempt < self.config.retry_times - 1:
+                    time.sleep(self.config.retry_delay * (attempt + 1))
+                    continue
+
+        raise last_error
+
+    def _handle_response(self, response: requests.Response) -> dict:
+        try:
+            data = response.json()
+        except Exception as e:
+            raise APIError(
+                f"响应解析失败: {str(e)}, logid: {response.headers.get('X-Tt-Logid')}, 响应内容: {response.text[:200]}",
+                status_code=response.status_code,
+            )
+
+        try:
+            response.raise_for_status()
+        except requests.exceptions.HTTPError as e:
+            error_msg = (
+                f"HTTP 错误: {str(e)}, logid: {response.headers.get('X-Tt-Logid')}"
+            )
+            if data:
+                error_msg += f", 响应数据: {data}"
+            raise APIError(
+                error_msg, status_code=response.status_code, response_data=data
+            )
+
+        return data
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass

local_coze/core/config.py

@@ -0,0 +1,58 @@
+import os
+from typing import Optional
+
+from .exceptions import ConfigurationError
+
+
+class Config:
+    DEFAULT_RETRY_TIMES = 1
+    DEFAULT_RETRY_DELAY = 1.0
+    DEFAULT_TIMEOUT = 900
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        base_model_url: Optional[str] = None,
+        retry_times: int = DEFAULT_RETRY_TIMES,
+        retry_delay: float = DEFAULT_RETRY_DELAY,
+        timeout: int = DEFAULT_TIMEOUT,
+    ):
+        self.api_key = api_key or self._get_env_var("COZE_WORKLOAD_IDENTITY_API_KEY")
+        self.base_url = base_url or self._get_env_var("COZE_INTEGRATION_BASE_URL")
+        self.base_model_url = base_model_url or self._get_env_var(
+            "COZE_INTEGRATION_MODEL_BASE_URL"
+        )
+        self.retry_times = retry_times
+        self.retry_delay = retry_delay
+        self.timeout = timeout
+
+        self._validate()
+
+    def _get_env_var(self, key: str) -> str:
+        value = os.getenv(key)
+        if not value:
+            raise ConfigurationError(
+                f"环境变量 {key} 未设置，请确保已正确配置", missing_key=key
+            )
+        return value
+
+    def _validate(self):
+        if not self.api_key:
+            raise ConfigurationError("API Key 未配置")
+        if not self.base_url and not self.base_model_url:
+            raise ConfigurationError("Base URL 未配置")
+
+    def get_headers(self, ctx_headers: Optional[dict] = None) -> dict:
+        try:
+            from .. import __version__
+        except ImportError:
+            __version__ = "0.0.0"
+
+        headers = {}
+        if ctx_headers:
+            headers.update(ctx_headers)
+        headers.setdefault("Content-Type", "application/json")
+        headers.setdefault("Authorization", f"Bearer {self.api_key}")
+        headers.setdefault("X-Client-Sdk", f"coze-coding-dev-sdk-python/{__version__}")
+        return headers