@petercjl/seedaudiocli 0.1.2 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @petercjl/seedaudiocli
 
-EvoLink Seed Audio CLI with a portable companion Skill. Requires Node.js 22+ and Python 3.9+ with SSL; no Python third-party packages are needed.
+Official Volcengine Seed Audio CLI with a portable companion Skill. Requires Node.js 22+ and Python 3.9+ with SSL; no Python third-party packages are needed.
 
 ## Install and configure
 
@@ -27,7 +27,7 @@ Credentials persist outside the npm installation:
 
 macOS/Linux files use mode 0600. Windows relies on the user's profile directory ACL; administrators should keep that directory private. Import validates local structure and does not make a paid API call. `auth status` reports local availability, not remote key validity. Environment variables override saved configuration. Network errors do not clear credentials.
 
-An existing configuration requires `--replace`; replacement creates a recoverable sibling backup before atomic write. Backups contain credentials too. Keep them private. Package uninstall/reinstall preserves configuration and task history. Existing env configurations remain supported. Legacy `config init --import-key-file FILE` remains available for older note-format files; new distribution uses `config import`.
+An existing configuration requires `--replace`; replacement creates a recoverable sibling backup before atomic write. Backups contain credentials too. Keep them private. Package uninstall/reinstall preserves configuration and task history. Official env configurations are supported. To migrate an existing installation, import the new official configuration with `--replace`. Relay endpoints and relay model IDs are rejected. Obtain a Doubao Speech API key with Seed Audio access; an Ark API key is a different credential.
 
 ## Generate and recover
 
@@ -37,7 +37,13 @@ seedaudiocli generate text --prompt "Generate five seconds of instrumental piano
 seedaudiocli task wait TASK_ID --download ./audio
 ```
 
-Actual generation can incur provider charges. Save the returned task ID and recover it instead of submitting again. Unknown submission outcomes require provider/history inspection. Reference modes and parameter limits are documented by `generate --help` and the bundled Skill.
+Actual generation can incur provider charges. The official API returns audio synchronously. The CLI records a local ID before its single POST, then saves the response and audio privately. `task get`, `task wait` and `task download` recover saved local results without network calls. There is no remote task polling. A timeout or interrupted submission is marked unknown; inspect its local record and provider billing evidence before explicitly authorizing another attempt with `--force`. A repeated successful request reuses the cached result.
+
+The fixed endpoint is `https://openspeech.bytedance.com/api/v3/tts/create`, using `X-Api-Key` and model `seed-audio-1.0`. Prompts accept 1–3000 characters. Use `--audio-file` for local recordings or `--audio-reference` for preset speakers/public URLs (up to three total); address them with `@音频1` through `@音频3`. Use one `--image-file` or `--image-url` for image guidance. Local files are encoded directly in the official request. References are limited to 10 MiB each; audio must be at most 30 seconds. Audio and image modes are exclusive. `--speech-rate` and `--loudness-rate` are integers from -50 to 100 (0 unchanged), and `--pitch-rate` is -12 to 12. `--subtitle` saves returned subtitle data next to the audio.
+
+Outputs support mp3, wav, pcm and ogg_opus. Select compatible sample rates with the CLI help: mp3 excludes 40000 Hz and ogg_opus requires 48000 Hz. Output files are never silently overwritten. Old history remains on disk; official records are stored separately.
+
+Protocol reference: [Volcengine Seed Audio HTTP documentation](https://docs.volcengine.com/docs/DoubaoVoice/audio-generation-http?lang=zh).
 
 ## Agent installation
 

package/capabilities.json

@@ -20,6 +20,7 @@
     "task get",
     "task wait",
     "task url",
+    "task download",
     "task jobs",
     "payload validate",
     "payload submit",
@@ -50,7 +51,8 @@
     "import": "seedaudiocli config import FILE [--replace]",
     "side_effects": "Local file write, backup on replacement; no remote call",
     "missing": "CONFIG_REQUIRED",
-    "secrets_in_output": false
+    "secrets_in_output": false,
+    "migration": "Import official configuration with --replace; backup is automatic; relay endpoints/models are rejected."
   },
   "update": {
     "trigger": "before-every-run",
@@ -64,10 +66,15 @@
     "managed_skills": "synchronized with backups; edited content preserved"
   },
   "generation": {
-    "provider": "EvoLink",
-    "model": "doubao-seed-audio-1-0",
+    "provider": "Volcengine",
+    "endpoint": "https://openspeech.bytedance.com/api/v3/tts/create",
+    "authentication": "X-Api-Key (Doubao Speech)",
+    "model": "seed-audio-1.0",
+    "mode": "synchronous",
     "paid": true,
     "submit_retry": false,
-    "recovery": "Use saved task ID; unknown submit outcome requires inspection before resubmission"
+    "local_references": true,
+    "remote_polling": false,
+    "recovery": "Persist local record before POST; save response and audio; export locally by record ID. Unknown outcomes require inspection and explicit authorization before --force."
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/seedaudiocli",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Seed Audio CLI with portable Agent skill and persistent user credentials",
   "type": "module",
   "bin": {

package/seedaudiocli/__init__.py

@@ -1 +1,9 @@
-__version__ = "0.1.0"
+"""Version follows the canonical npm package metadata."""
+import json
+from pathlib import Path
+
+try:
+    __version__ = json.loads((Path(__file__).resolve().parent.parent / "package.json").read_text(encoding="utf-8"))["version"]
+except (OSError, ValueError, KeyError):
+    from importlib.metadata import version
+    __version__ = version("seedaudiocli")

package/seedaudiocli/cli.py

@@ -4,12 +4,15 @@ import argparse
 import json
 import os
 import sys
+import time
+import uuid
+import hashlib
 from pathlib import Path
 from types import SimpleNamespace
 from typing import Any
 
 from . import __version__
-from . import evolink
+from . import official
 from .config import (
     DEFAULT_BASE_URL,
     DEFAULT_MODEL,
@@ -22,7 +25,7 @@ from .config import (
     import_config,
     ConfigError,
 )
-from .jobs import append_job, append_status, find_by_hash, read_jobs
+from .jobs import root, job_dir, save_record, read_job, write_json, recover_audio, export_audio, find_by_hash, read_jobs, validate_output_name
 from .payloads import build_payload, read_prompt, request_hash, validate_payload
 
 
@@ -31,20 +34,19 @@ def print_json(data: Any) -> None:
 
 
 def add_generation_args(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("--prompt", help="Prompt text, max 1500 characters.")
+    parser.add_argument("--prompt", help="Prompt text, max 3000 characters.")
     parser.add_argument("--prompt-file", help="Path to a UTF-8 prompt text file.")
-    parser.add_argument("--model", help="Override model id. Default: doubao-seed-audio-1-0.")
+    parser.add_argument("--model", help="Override model id. Default: seed-audio-1.0.")
     parser.add_argument("--format", choices=["wav", "mp3", "pcm", "ogg_opus"], help="Output audio format.")
-    parser.add_argument("--sample-rate", type=int, choices=[8000, 16000, 24000, 32000, 44100, 48000])
-    parser.add_argument("--speech-rate", type=float, help="Speech-rate multiplier from 0.5 to 2.0.")
-    parser.add_argument("--loudness-rate", type=float, help="Loudness multiplier from 0.5 to 2.0.")
+    parser.add_argument("--sample-rate", type=int, choices=[8000, 16000, 24000, 32000, 40000, 44100, 48000])
+    parser.add_argument("--speech-rate", type=int, help="Speech-rate adjustment from -50 to 100; 0 is unchanged.")
+    parser.add_argument("--loudness-rate", type=int, help="Loudness adjustment from -50 to 100; 0 is unchanged.")
     parser.add_argument("--pitch-rate", type=int, help="Pitch adjustment in semitones from -12 to 12.")
-    parser.add_argument("--callback-url", help="HTTPS callback URL for task completion.")
+    parser.add_argument("--subtitle", action="store_true", help="Return timestamped subtitles when supported.")
     parser.add_argument("--dry-run", action="store_true", help="Print payload without creating a task.")
     parser.add_argument("--force", action="store_true", help="Create a new task even if the same request hash exists.")
-    parser.add_argument("--wait", action="store_true", help="Wait until the task reaches a terminal state.")
-    parser.add_argument("--interval", type=int, default=5, help="Polling interval in seconds for --wait.")
-    parser.add_argument("--timeout", type=int, default=1800, help="Polling timeout in seconds for --wait.")
+    parser.add_argument("--wait", action="store_true", help="Compatibility flag: official generation always waits for its response.")
+    parser.add_argument("--timeout", type=int, default=300, help="HTTP request timeout in seconds; a timeout never resubmits.")
     parser.add_argument("--download", help="Download completed audio to this directory. Implies --wait.")
     parser.add_argument("--output-name", help="Filename stem for downloaded audio. Defaults to task id.")
 
@@ -63,70 +65,69 @@ def generation_payload_from_args(args: argparse.Namespace) -> dict[str, Any]:
         speech_rate=args.speech_rate,
         loudness_rate=args.loudness_rate,
         pitch_rate=args.pitch_rate,
-        callback_url=args.callback_url,
+        enable_subtitle=args.subtitle,
+        audio_files=list(getattr(args, "audio_file", None) or []),
+        image_files=list(getattr(args, "image_file", None) or []),
     )
 
 
-def download_from_response(response: dict[str, Any], out_dir: Path, output_name: str | None = None) -> list[str]:
-    urls = evolink.extract_audio_urls(response)
-    if not urls:
-        return []
-    formats: list[str | None] = []
-    for item in response.get("result_data") or []:
-        if isinstance(item, dict):
-            formats.append(item.get("format"))
-    out_dir.mkdir(parents=True, exist_ok=True)
-    task_id = str(response.get("id") or "audio")
-    downloaded: list[str] = []
-    for idx, url in enumerate(urls, 1):
-        result_format = formats[idx - 1] if idx - 1 < len(formats) else None
-        ext = {"ogg_opus": "ogg", "pcm": "pcm"}.get(str(result_format), str(result_format or "")) or evolink.infer_extension(url)
-        stem = output_name or task_id
-        suffix = "" if len(urls) == 1 else f"_{idx}"
-        out_path = out_dir / f"{stem}{suffix}.{ext}"
-        evolink.download_url(url, out_path)
-        downloaded.append(str(out_path))
-    return downloaded
-
-
-def submit_or_print(payload: dict[str, Any], args: argparse.Namespace) -> int:
+def submit_or_print(payload, args):
     errors = validate_payload(payload)
     h = request_hash(payload)
     if errors:
-        result: dict[str, Any] = {"ok": False, "errors": errors}
-        if args.dry_run:
-            result["payload"] = payload
-            result["request_hash"] = h
-        print_json(result)
+        print_json({"ok": False, "code": "PAYLOAD_INVALID", "errors": errors})
         return 2
+    if args.timeout <= 0:
+        raise ValueError("timeout must be positive.")
+    validate_output_name(args.output_name)
+    if args.download and Path(args.download).expanduser().exists() and not Path(args.download).expanduser().is_dir():
+        raise ValueError("download destination must be a directory.")
     if args.dry_run:
-        print_json({"ok": True, "dry_run": True, "request_hash": h, "payload": payload})
-        return 0
-
-    existing = find_by_hash(h)
-    if existing and not args.force:
-        print_json({"ok": True, "deduped": True, "request_hash": h, "job": existing})
+        print_json({"ok": True, "dry_run": True, "request_hash": h, "payload": payload,
+                    "provider": "Volcengine", "endpoint": DEFAULT_BASE_URL + "/api/v3/tts/create"})
         return 0
-
-    response = evolink.create_task(payload)
-    task_id = evolink.extract_task_id(response)
-    append_job({"event": "create", "request_hash": h, "task_id": task_id, "payload": payload, "response": response})
-
-    result: dict[str, Any] = {"ok": True, "request_hash": h, "task_id": task_id, "response": response}
-    should_wait = args.wait or bool(args.download)
-    if should_wait and task_id:
-        final = evolink.wait_for_task(task_id, interval=args.interval, timeout=args.timeout)
-        status = evolink.extract_status(final)
-        append_status(task_id, status, final)
-        result["final_status"] = status
-        result["final_response"] = final
+    seedaudio_base_url()
+    key = seedaudio_api_key()
+    # Account-scoped deduplication avoids reusing another credential's result.
+    h = hashlib.sha256((h + (key or "")).encode()).hexdigest()
+    lock = root() / (h + ".lock")
+    try:
+        fd = os.open(lock, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError:
+        raise official.SeedAudioError("An identical request is in progress or was interrupted. Inspect task jobs before clearing its local lock.", "REQUEST_BUSY") from None
+    os.close(fd)
+    try:
+        existing = find_by_hash(h)
+        if existing and not args.force and existing["status"] != "failed":
+            record = recover_audio(existing)
+            if record["status"] != "completed":
+                raise official.SeedAudioError("Previous generation outcome is unknown. Inspect the local record; a new paid attempt requires explicit authorization and --force.", "SUBMISSION_UNKNOWN", details={"task_id": record["task_id"]})
+            result = {"ok": True, "deduped": True, "task_id": record["task_id"], "job": record}
+        else:
+            task_id = str(uuid.uuid4())
+            job_dir(task_id).mkdir(mode=0o700)
+            record = {"task_id": task_id, "request_id": task_id, "request_hash": h, "provider": "Volcengine",
+                      "status": "submitting", "created_at": time.time(), "format": payload.get("audio_config", {}).get("format", "wav")}
+            save_record(record)
+            # Persist the local ID before sending the only billable request.
+            print(json.dumps({"event": "submitting", "task_id": task_id}), file=sys.stderr, flush=True)
+            try:
+                response = official.create_audio(payload, task_id, args.timeout)
+                write_json(job_dir(task_id) / "response.json", response)
+                record = recover_audio(record)
+            except official.SeedAudioError as e:
+                record.update(status="unknown" if e.code in {"SUBMISSION_UNKNOWN", "OUTPUT_CONTRACT_FAILED"} else "failed",
+                              error_code=e.code, details=e.details)
+                save_record(record)
+                e.details.setdefault("task_id", task_id)
+                raise
+            result = {"ok": True, "task_id": task_id, "job": record}
         if args.download:
-            downloaded = download_from_response(final, Path(args.download).expanduser(), args.output_name)
-            result["downloaded_to"] = downloaded
-    print_json(result)
-    if result.get("final_status") and result["final_status"] != "completed":
-        return 2
-    return 0
+            result["downloaded_to"] = export_audio(record, args.download, args.output_name)
+        print_json(result)
+        return 0
+    finally:
+        lock.unlink()
 
 
 def cmd_config(args: argparse.Namespace) -> int:
@@ -139,7 +140,6 @@ def cmd_config(args: argparse.Namespace) -> int:
     if args.config_cmd == "init":
         path = write_default_env(
             import_current_env=args.import_env,
-            import_key_file=args.import_key_file,
             overwrite=args.overwrite,
         )
         print(f"Wrote config: {path}")
@@ -193,45 +193,37 @@ def cmd_models(_: argparse.Namespace) -> int:
             "default": DEFAULT_MODEL,
             "configured": seedaudio_model(),
             "base_url_default": DEFAULT_BASE_URL,
-            "notes": "EvoLink currently exposes doubao-seed-audio-1-0 for this CLI.",
+            "notes": "Official Doubao Speech Seed Audio; synchronous HTTP response with local result recovery.",
         }
     )
     return 0
 
 
 def cmd_generate(args: argparse.Namespace) -> int:
+    if args.generate_cmd == "audio-ref" and not (args.audio_reference or args.audio_file):
+        raise ValueError("audio-ref requires --audio-reference or --audio-file.")
+    if args.generate_cmd == "image-ref" and not (args.image_url or args.image_file):
+        raise ValueError("image-ref requires --image-url or --image-file.")
     payload = generation_payload_from_args(args)
     return submit_or_print(payload, args)
 
 
-def cmd_task(args: argparse.Namespace) -> int:
-    if args.task_cmd == "get":
-        response = evolink.get_task(args.task_id)
-        append_status(args.task_id, evolink.extract_status(response), response)
-        print_json(response)
-        return 0
-    if args.task_cmd == "wait":
-        response = evolink.wait_for_task(args.task_id, interval=args.interval, timeout=args.timeout)
-        status = evolink.extract_status(response)
-        append_status(args.task_id, status, response)
-        result: dict[str, Any] = {"task_id": args.task_id, "status": status, "response": response}
-        if args.download:
-            result["downloaded_to"] = download_from_response(response, Path(args.download).expanduser(), args.output_name)
-        print_json(result)
-        return 0 if status == "completed" else 2
-    if args.task_cmd == "url":
-        response = evolink.get_task(args.task_id)
-        status = evolink.extract_status(response)
-        append_status(args.task_id, status, response)
-        result: dict[str, Any] = {"task_id": args.task_id, "status": status, "urls": evolink.extract_audio_urls(response)}
-        if args.include_response:
-            result["response"] = response
-        print_json(result)
-        return 0 if result["urls"] else 2
+def cmd_task(args):
     if args.task_cmd == "jobs":
-        print_json({"job_store": str(job_store_path()), "jobs": read_jobs()[-args.limit :]})
+        if args.limit < 1:
+            raise ValueError("limit must be positive.")
+        print_json({"ok": True, "job_store": str(root()), "jobs": read_jobs()[-args.limit:]})
         return 0
-    raise SystemExit("unknown task command")
+    record = recover_audio(read_job(args.task_id))
+    result = {"ok": record["status"] == "completed", "task_id": args.task_id, "job": record,
+              "remote_polling": False}
+    if args.task_cmd in {"download", "wait"} and args.download:
+        result["downloaded_to"] = export_audio(record, args.download, args.output_name)
+    if args.task_cmd == "url":
+        result["urls"] = [record["url"]] if record.get("url") else []
+        result["note"] = "Provider URL may expire; cached local audio remains available."
+    print_json(result)
+    return 0 if result["ok"] else 2
 
 
 def cmd_payload(args: argparse.Namespace) -> int:
@@ -248,7 +240,6 @@ def cmd_payload(args: argparse.Namespace) -> int:
             dry_run=False,
             force=args.force,
             wait=args.wait,
-            interval=args.interval,
             timeout=args.timeout,
             download=args.download,
             output_name=args.output_name,
@@ -258,7 +249,7 @@ def cmd_payload(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="seedaudiocli", description="System CLI for EvoLink Doubao Seed-Audio 1.0 generation.")
+    parser = argparse.ArgumentParser(prog="seedaudiocli", description="Official Volcengine Seed Audio generation and local result recovery.")
     parser.add_argument("--version", action="version", version=f"seedaudiocli {__version__}")
     sub = parser.add_subparsers(dest="cmd", required=True)
 
@@ -275,7 +266,6 @@ def build_parser() -> argparse.ArgumentParser:
     config_import.add_argument("--replace", action="store_true", help="Back up existing configuration before replacement.")
     config_init = config_sub.add_parser("init", help="Create env config file.")
     config_init.add_argument("--import-env", action="store_true", help="Copy current SEEDAUDIO_* values into the env file.")
-    config_init.add_argument("--import-key-file", help="Import Seed-Audio EvoLink key block from a local note file.")
     config_init.add_argument("--overwrite", action="store_true", help="Overwrite existing env file.")
     config.set_defaults(func=cmd_config)
 
@@ -299,28 +289,34 @@ def build_parser() -> argparse.ArgumentParser:
 
     gen_audio = gen_sub.add_parser("audio-ref", help="Reference-audio or preset-voice generation.")
     add_generation_args(gen_audio)
-    gen_audio.add_argument("--audio-reference", action="append", required=True, help="Preset voice_type or reference-audio URL. Repeat up to 3 times.")
+    gen_audio.add_argument("--audio-reference", action="append", help="Preset speaker ID or audio URL; reference order precedes audio-file entries.")
+    gen_audio.add_argument("--audio-file", action="append", help="Local reference recording up to 10 MiB and 30 seconds; repeat up to 3 total references.")
     gen_audio.set_defaults(func=cmd_generate)
 
     gen_image = gen_sub.add_parser("image-ref", help="Reference-image-guided audio generation.")
     add_generation_args(gen_image)
-    gen_image.add_argument("--image-url", action="append", required=True, help="Public jpeg/png/webp image URL. Exactly one is supported by the API.")
+    gen_image.add_argument("--image-url", action="append", help="Public jpeg/png/webp URL; exactly one image reference.")
+    gen_image.add_argument("--image-file", action="append", help="Local jpeg/png/webp image up to 10 MiB.")
     gen_image.set_defaults(func=cmd_generate)
 
-    task = sub.add_parser("task", help="Task status, wait, URLs, and history.")
+    task = sub.add_parser("task", help="Local official generation records and cached audio; no remote polling.")
     task_sub = task.add_subparsers(dest="task_cmd", required=True)
-    task_get = task_sub.add_parser("get", help="Fetch raw task JSON.")
+    task_get = task_sub.add_parser("get", help="Read a local generation record.")
     task_get.add_argument("task_id")
     task_get.set_defaults(func=cmd_task)
 
-    task_wait = task_sub.add_parser("wait", help="Wait for task completion.")
+    task_wait = task_sub.add_parser("wait", help="Recover a saved response locally (compatibility alias).")
     task_wait.add_argument("task_id")
-    task_wait.add_argument("--interval", type=int, default=5)
-    task_wait.add_argument("--timeout", type=int, default=1800)
     task_wait.add_argument("--download", help="Download completed audio to this directory.")
     task_wait.add_argument("--output-name", help="Filename stem for downloaded audio.")
     task_wait.set_defaults(func=cmd_task)
 
+    task_download = task_sub.add_parser("download", help="Export cached audio without a new generation.")
+    task_download.add_argument("task_id")
+    task_download.add_argument("--download", required=True)
+    task_download.add_argument("--output-name")
+    task_download.set_defaults(func=cmd_task)
+
     task_url = task_sub.add_parser("url", help="Print completed audio URLs.")
     task_url.add_argument("task_id")
     task_url.add_argument("--include-response", action="store_true")
@@ -342,8 +338,7 @@ def build_parser() -> argparse.ArgumentParser:
     payload_submit.add_argument("file")
     payload_submit.add_argument("--force", action="store_true")
     payload_submit.add_argument("--wait", action="store_true")
-    payload_submit.add_argument("--interval", type=int, default=5)
-    payload_submit.add_argument("--timeout", type=int, default=1800)
+    payload_submit.add_argument("--timeout", type=int, default=300)
     payload_submit.add_argument("--download")
     payload_submit.add_argument("--output-name")
     payload_submit.set_defaults(func=cmd_payload)
@@ -356,7 +351,6 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
     try:
         network = ((args.cmd == "generate" and not args.dry_run)
-                   or (args.cmd == "task" and args.task_cmd != "jobs")
                    or (args.cmd == "payload" and args.payload_cmd == "submit"))
         if network and not seedaudio_api_key():
             if sys.stdin.isatty():
@@ -367,7 +361,7 @@ def main(argv: list[str] | None = None) -> int:
     except ConfigError as e:
         print_json({"ok": False, "code": e.code, "error": str(e)})
         return 2
-    except (ValueError, evolink.SeedAudioError) as e:
+    except (ValueError, official.SeedAudioError) as e:
         message = str(e)
         try:
             key = seedaudio_api_key()
@@ -375,7 +369,7 @@ def main(argv: list[str] | None = None) -> int:
                 message = message.replace(key, "[REDACTED]")
         except ConfigError:
             pass
-        print_json({"ok": False, "code": getattr(e, "code", "REQUEST_FAILED"), "error": message})
+        print_json({"ok": False, "code": getattr(e, "code", "REQUEST_FAILED"), "error": message, "details": getattr(e, "details", {})})
         return 1
     except (OSError, EOFError, KeyboardInterrupt):
         print_json({"ok": False, "code": "LOCAL_OPERATION_FAILED", "error": "Local operation failed or was cancelled."})

package/seedaudiocli/config.py

@@ -10,8 +10,8 @@ from urllib.parse import urlparse
 
 
 APP_NAME = "seedaudiocli"
-DEFAULT_BASE_URL = "https://api.evolink.ai"
-DEFAULT_MODEL = "doubao-seed-audio-1-0"
+DEFAULT_BASE_URL = "https://openspeech.bytedance.com"
+DEFAULT_MODEL = "seed-audio-1.0"
 DEFAULT_FORMAT = "mp3"
 DEFAULT_SAMPLE_RATE = "44100"
 
@@ -69,12 +69,14 @@ def validate_config(values: dict[str, str], require_key: bool = True) -> dict[st
         valid_url = False
     if not valid_url:
         raise ConfigError("CONFIG_INVALID", "API base URL must be HTTPS without credentials, query or fragment.")
+    if base.rstrip("/") != DEFAULT_BASE_URL:
+        raise ConfigError("CONFIG_MIGRATION_REQUIRED", "Import an official Doubao Speech configuration; this version only connects to openspeech.bytedance.com.")
     if values.get("SEEDAUDIO_DEFAULT_FORMAT", DEFAULT_FORMAT) not in {"mp3", "wav", "pcm", "ogg_opus"}:
         raise ConfigError("CONFIG_INVALID", "Unsupported audio format.")
-    if values.get("SEEDAUDIO_DEFAULT_SAMPLE_RATE", DEFAULT_SAMPLE_RATE) not in {"8000", "16000", "24000", "32000", "44100", "48000"}:
+    if values.get("SEEDAUDIO_DEFAULT_SAMPLE_RATE", DEFAULT_SAMPLE_RATE) not in {"8000", "16000", "24000", "32000", "40000", "44100", "48000"}:
         raise ConfigError("CONFIG_INVALID", "Unsupported sample rate.")
-    if not values.get("SEEDAUDIO_MODEL", DEFAULT_MODEL).strip():
-        raise ConfigError("CONFIG_INVALID", "Model must not be empty.")
+    if values.get("SEEDAUDIO_MODEL", DEFAULT_MODEL) != DEFAULT_MODEL:
+        raise ConfigError("CONFIG_MIGRATION_REQUIRED", "Import an official configuration using model seed-audio-1.0.")
     return {**values, "SEEDAUDIO_API_KEY": key}
 
 
@@ -184,18 +186,17 @@ def seedaudio_api_key() -> str | None:
 
 
 def seedaudio_base_url() -> str:
-    raw = get_setting("SEEDAUDIO_BASE_URL", DEFAULT_BASE_URL) or DEFAULT_BASE_URL
-    raw = raw.rstrip("/")
-    suffix = "/v1/audios/generations"
-    if raw.endswith(suffix):
-        raw = raw[: -len(suffix)]
-    if raw.endswith("/v1"):
-        raw = raw[: -len("/v1")]
-    return raw.rstrip("/")
+    raw = (get_setting("SEEDAUDIO_BASE_URL", DEFAULT_BASE_URL) or DEFAULT_BASE_URL).rstrip("/")
+    if raw != DEFAULT_BASE_URL:
+        raise ConfigError("CONFIG_MIGRATION_REQUIRED", "Only the official Doubao Speech endpoint is supported; import the official configuration.")
+    return raw
 
 
 def seedaudio_model() -> str:
-    return get_setting("SEEDAUDIO_MODEL", DEFAULT_MODEL) or DEFAULT_MODEL
+    model = get_setting("SEEDAUDIO_MODEL", DEFAULT_MODEL) or DEFAULT_MODEL
+    if model != DEFAULT_MODEL:
+        raise ConfigError("CONFIG_MIGRATION_REQUIRED", "The configured model must be seed-audio-1.0.")
+    return model
 
 
 def default_format() -> str:
@@ -207,33 +208,8 @@ def default_sample_rate() -> int:
     return int(value)
 
 
-def parse_evolink_seed_audio_file(path: Path) -> tuple[str | None, str | None]:
-    if not path.exists():
-        return None, None
-    text = path.read_text(errors="ignore")
-    in_seed = False
-    api_key: str | None = None
-    base_url: str | None = None
-    for raw in text.splitlines():
-        line = raw.strip()
-        low = line.lower()
-        if "seed-audio" in low and "evolink" in low:
-            in_seed = True
-            continue
-        if not in_seed:
-            continue
-        norm = line.replace("：", ":")
-        if norm.lower().startswith("base url") and ":" in norm:
-            base_url = norm.split(":", 1)[1].strip()
-        elif norm.lower().startswith("api key") and ":" in norm:
-            api_key = norm.split(":", 1)[1].strip()
-            break
-    return api_key, base_url
-
-
 def write_default_env(
     import_current_env: bool = False,
-    import_key_file: str | None = None,
     overwrite: bool = False,
 ) -> Path:
     path = config_path()
@@ -251,11 +227,6 @@ def write_default_env(
         else DEFAULT_SAMPLE_RATE
     )
 
-    if import_key_file:
-        key, base = parse_evolink_seed_audio_file(Path(import_key_file).expanduser())
-        current_key = key or current_key
-        current_base = base or current_base
-
     save_config({"SEEDAUDIO_API_KEY": current_key, "SEEDAUDIO_BASE_URL": current_base,
                  "SEEDAUDIO_MODEL": current_model, "SEEDAUDIO_DEFAULT_FORMAT": current_format,
                  "SEEDAUDIO_DEFAULT_SAMPLE_RATE": current_sample_rate}, replace=overwrite, require_key=False)

package/seedaudiocli/jobs.py

@@ -1,46 +1,134 @@
 from __future__ import annotations
 
+import base64
 import json
+import os
+import re
+import shutil
+import tempfile
 import time
 from pathlib import Path
-from typing import Any
 
-from .config import job_store_path
+from .config import state_dir
+from .official import SeedAudioError
 
 
-TERMINAL_STATES = {"completed", "failed", "cancelled", "canceled", "expired"}
+def root():
+    p = state_dir() / "official"
+    p.mkdir(parents=True, exist_ok=True, mode=0o700)
+    return p
 
 
-def append_job(record: dict[str, Any], path: Path | None = None) -> None:
-    path = path or job_store_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    record = {"created_at": int(time.time()), **record}
-    with path.open("a", encoding="utf-8") as f:
-        f.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
+def job_dir(task_id):
+    if not re.fullmatch(r"[a-f0-9-]{36}", task_id):
+        raise SeedAudioError("Expected a local official generation record ID.", "TASK_NOT_FOUND")
+    return root() / task_id
 
 
-def read_jobs(path: Path | None = None) -> list[dict[str, Any]]:
-    paths = [path or job_store_path()]
-    jobs: list[dict[str, Any]] = []
-    for read_path in paths:
-        if not read_path.exists():
+def write_json(path, value):
+    fd, tmp = tempfile.mkstemp(prefix=".record-", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(value, f, ensure_ascii=False)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+        os.chmod(path, 0o600)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+def save_record(record):
+    write_json(job_dir(record["task_id"]) / "record.json", record)
+
+
+def read_job(task_id):
+    p = job_dir(task_id) / "record.json"
+    if not p.is_file():
+        raise SeedAudioError("Local official generation record not found.", "TASK_NOT_FOUND")
+    return json.loads(p.read_text(encoding="utf-8"))
+
+
+def read_jobs():
+    jobs = []
+    for p in root().glob("*/record.json"):
+        try:
+            jobs.append(json.loads(p.read_text(encoding="utf-8")))
+        except (ValueError, OSError):
             continue
-        for line in read_path.read_text(encoding="utf-8").splitlines():
-            if not line.strip():
-                continue
-            try:
-                jobs.append(json.loads(line))
-            except json.JSONDecodeError:
-                continue
-    return jobs
-
-
-def find_by_hash(request_hash: str) -> dict[str, Any] | None:
-    for job in reversed(read_jobs()):
-        if job.get("request_hash") == request_hash and job.get("task_id"):
-            return job
+    return sorted(jobs, key=lambda x: x.get("created_at", 0))
+
+
+def find_by_hash(h):
+    for record in reversed(read_jobs()):
+        if record.get("request_hash") == h:
+            return record
     return None
 
 
-def append_status(task_id: str, status: str, response: dict[str, Any] | None = None) -> None:
-    append_job({"event": "status", "task_id": task_id, "status": status, "response": response or {}})
+def recover_audio(record):
+    d = job_dir(record["task_id"])
+    response_path = d / "response.json"
+    if not response_path.is_file():
+        return record
+    # Raw response is saved before decoding/export, so local failures are recoverable.
+    response = json.loads(response_path.read_text(encoding="utf-8"))
+    try:
+        audio = base64.b64decode(response.get("audio", ""), validate=True)
+        if not audio:
+            raise ValueError()
+    except (ValueError, TypeError):
+        raise SeedAudioError("No valid audio bytes in the saved response; do not resubmit automatically.", "OUTPUT_CONTRACT_FAILED") from None
+    fmt = record["format"]
+    p = d / ("audio." + ("ogg" if fmt == "ogg_opus" else fmt))
+    if p.exists():
+        if p.read_bytes() != audio:
+            raise SeedAudioError("Cached audio differs from the saved response.", "OUTPUT_EXISTS")
+    else:
+        fd = os.open(p, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(fd, "wb") as f:
+            f.write(audio)
+    record.update(status="completed", audio_path=str(p), bytes=len(audio),
+                  duration=response.get("duration"), original_duration=response.get("original_duration"),
+                  logid=response.get("logid"), url=response.get("url"))
+    if response.get("subtitle") is not None:
+        sp = d / "subtitle.json"
+        if not sp.exists():
+            write_json(sp, response["subtitle"])
+        record["subtitle_path"] = str(sp)
+    save_record(record)
+    return record
+
+
+def validate_output_name(stem):
+    if stem and (stem in {".", ".."} or any(c in stem for c in '/\\<>:"|?*') or any(ord(c) < 32 for c in stem)):
+        raise ValueError("output-name must be a filename stem without path separators.")
+
+
+def export_audio(record, destination, output_name=None):
+    record = recover_audio(record)
+    if record.get("status") != "completed":
+        raise SeedAudioError("No saved successful response. Official API has no remote task-query operation.", "SUBMISSION_UNKNOWN")
+    stem = output_name or record["task_id"]
+    if stem in {".", ".."} or any(c in stem for c in '/\\<>:"|?*') or any(ord(c) < 32 for c in stem):
+        raise ValueError("output-name must be a filename stem without path separators.")
+    out = Path(destination).expanduser().resolve()
+    out.mkdir(parents=True, exist_ok=True)
+    paths = []
+    for field, suffix in [("audio_path", Path(record["audio_path"]).suffix), ("subtitle_path", ".subtitle.json")]:
+        if field not in record:
+            continue
+        src = Path(record[field])
+        target = out / (stem + suffix)
+        if target.is_symlink():
+            raise SeedAudioError("Output target is a symlink.", "OUTPUT_EXISTS")
+        if target.exists():
+            if not target.is_file() or target.read_bytes() != src.read_bytes():
+                raise SeedAudioError("Output already exists; choose another output-name.", "OUTPUT_EXISTS")
+        else:
+            fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            with os.fdopen(fd, "wb") as f, src.open("rb") as source:
+                shutil.copyfileobj(source, f)
+        paths.append(str(target))
+    return paths

package/seedaudiocli/official.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from .config import seedaudio_api_key, seedaudio_base_url
+
+
+class SeedAudioError(RuntimeError):
+    def __init__(self, message: str, code: str = "PROVIDER_FAILURE", *, details=None):
+        super().__init__(message)
+        self.code = code
+        self.details = details or {}
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def create_audio(payload: dict[str, Any], request_id: str, timeout: int = 300) -> dict:
+    # Validate destination before reading/sending the credential. No POST retry.
+    url = seedaudio_base_url() + "/api/v3/tts/create"
+    key = seedaudio_api_key()
+    if not key:
+        raise SeedAudioError("Import a Doubao Speech configuration file.", "CONFIG_REQUIRED")
+    req = urllib.request.Request(url, data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+                                headers={"X-Api-Key": key, "X-Api-Request-Id": request_id,
+                                         "Content-Type": "application/json"}, method="POST")
+    opener = urllib.request.build_opener(NoRedirect)
+    try:
+        with opener.open(req, timeout=timeout) as resp:
+            raw = resp.read()
+            logid = resp.headers.get("X-Tt-Logid")
+    except urllib.error.HTTPError as e:
+        logid = e.headers.get("X-Tt-Logid") if e.headers else None
+        try:
+            error = json.loads(e.read())
+        except (ValueError, OSError):
+            error = {}
+        if not isinstance(error, dict):
+            error = {}
+        code = "AUTH_REQUIRED" if e.code == 401 else "PERMISSION_REQUIRED" if e.code == 403 else "PROVIDER_FAILURE"
+        if e.code >= 500 or e.code == 408:
+            code = "SUBMISSION_UNKNOWN"
+        message = str(error.get("message", "Official service rejected the request.")).replace(key, "[REDACTED]")
+        raise SeedAudioError(message, code, details={"http_status": e.code,
+                            "provider_code": error.get("code"), "logid": logid,
+                            "request_id": request_id}) from None
+    except (urllib.error.URLError, TimeoutError, OSError):
+        raise SeedAudioError("Connection ended without a confirmed result. Do not automatically resubmit.",
+                             "SUBMISSION_UNKNOWN", details={"request_id": request_id}) from None
+    try:
+        data = json.loads(raw)
+        if not isinstance(data, dict):
+            raise ValueError()
+    except (ValueError, UnicodeError):
+        raise SeedAudioError("Official service returned an unreadable result; generation outcome is unknown.",
+                             "SUBMISSION_UNKNOWN", details={"request_id": request_id, "logid": logid}) from None
+    return {**data, "request_id": request_id, "logid": logid}

package/seedaudiocli/payloads.py

@@ -1,20 +1,21 @@
 from __future__ import annotations
 
+import base64
 import hashlib
 import json
 from pathlib import Path
+from urllib.parse import urlparse
 from typing import Any
 
 from .config import default_format, default_sample_rate, seedaudio_model
 
-
 FORMATS = {"wav", "mp3", "pcm", "ogg_opus"}
-SAMPLE_RATES = {8000, 16000, 24000, 32000, 44100, 48000}
+SAMPLE_RATES = {8000, 16000, 24000, 32000, 40000, 44100, 48000}
 
 
-def read_prompt(prompt: str | None, prompt_file: str | None) -> str:
+def read_prompt(prompt, prompt_file):
     if prompt and prompt_file:
-        raise ValueError("Use either --prompt or --prompt-file, not both.")
+        raise ValueError("Use either --prompt or --prompt-file.")
     if prompt_file:
         return Path(prompt_file).expanduser().read_text(encoding="utf-8").strip()
     if prompt:
@@ -22,86 +23,107 @@ def read_prompt(prompt: str | None, prompt_file: str | None) -> str:
     raise ValueError("Missing --prompt or --prompt-file.")
 
 
-def build_payload(
-    *,
-    prompt: str,
-    model: str | None = None,
-    audio_references: list[str] | None = None,
-    image_urls: list[str] | None = None,
-    output_format: str | None = None,
-    sample_rate: int | None = None,
-    speech_rate: float | None = None,
-    loudness_rate: float | None = None,
-    pitch_rate: int | None = None,
-    callback_url: str | None = None,
-) -> dict[str, Any]:
-    payload: dict[str, Any] = {
-        "model": model or seedaudio_model(),
-        "prompt": prompt,
-        "format": output_format or default_format(),
-        "sample_rate": sample_rate or default_sample_rate(),
-    }
-    if audio_references:
-        payload["audio_references"] = audio_references
-    if image_urls:
-        payload["image_urls"] = image_urls
-    if speech_rate is not None:
-        payload["speech_rate"] = speech_rate
-    if loudness_rate is not None:
-        payload["loudness_rate"] = loudness_rate
-    if pitch_rate is not None:
-        payload["pitch_rate"] = pitch_rate
-    if callback_url:
-        payload["callback_url"] = callback_url
-    return payload
-
-
-def validate_payload(payload: dict[str, Any]) -> list[str]:
-    errors: list[str] = []
-    prompt = payload.get("prompt")
-    if not isinstance(prompt, str) or not prompt.strip():
-        errors.append("prompt is required.")
-    elif len(prompt) > 1500:
-        errors.append("prompt must be <= 1500 characters.")
-
-    if payload.get("model") != "doubao-seed-audio-1-0":
-        errors.append("model must be doubao-seed-audio-1-0 unless the gateway adds another compatible model.")
-
-    fmt = payload.get("format")
+def local_reference(filename, kind):
+    p = Path(filename).expanduser()
+    allowed = {".wav", ".mp3", ".pcm", ".ogg", ".opus"} if kind == "audio" else {".jpg", ".jpeg", ".png", ".webp"}
+    if not p.is_file() or p.suffix.lower() not in allowed or not 0 < p.stat().st_size <= 10 * 1024 * 1024:
+        raise ValueError("Reference must be a supported non-empty file up to 10 MiB.")
+    return {kind + "_data": base64.b64encode(p.read_bytes()).decode("ascii")}
+
+
+def build_payload(*, prompt, model=None, audio_references=None, image_urls=None,
+                  audio_files=None, image_files=None, output_format=None, sample_rate=None,
+                  speech_rate=None, loudness_rate=None, pitch_rate=None, enable_subtitle=False):
+    config = {"format": output_format or default_format(), "sample_rate": sample_rate if sample_rate is not None else default_sample_rate()}
+    for key, value in [("speech_rate", speech_rate), ("loudness_rate", loudness_rate), ("pitch_rate", pitch_rate)]:
+        if value is not None:
+            config[key] = value
+    if enable_subtitle:
+        config["enable_subtitle"] = True
+    refs = [{"audio_url" if r.startswith(("http://", "https://")) else "speaker": r} for r in audio_references or []]
+    refs += [local_reference(f, "audio") for f in audio_files or []]
+    refs += [{"image_url": u} for u in image_urls or []]
+    refs += [local_reference(f, "image") for f in image_files or []]
+    result = {"model": model or seedaudio_model(), "text_prompt": prompt, "audio_config": config}
+    if refs:
+        result["references"] = refs
+    return result
+
+
+def validate_payload(payload):
+    if not isinstance(payload, dict):
+        return ["Payload must be a JSON object."]
+    errors = []
+    if set(payload) - {"model", "text_prompt", "references", "audio_config", "watermark"}:
+        errors.append("Unsupported top-level fields; use the official request schema.")
+    prompt = payload.get("text_prompt")
+    if not isinstance(prompt, str) or not prompt.strip() or len(prompt) > 3000:
+        errors.append("text_prompt must contain 1–3000 characters.")
+    if payload.get("model") != "seed-audio-1.0":
+        errors.append("model must be seed-audio-1.0.")
+    config = payload.get("audio_config", {})
+    if not isinstance(config, dict):
+        errors.append("audio_config must be an object.")
+        config = {}
+    if set(config) - {"format", "sample_rate", "speech_rate", "loudness_rate", "pitch_rate", "enable_subtitle"}:
+        errors.append("Unsupported audio_config fields.")
+    fmt = config.get("format", "wav")
+    rate = config.get("sample_rate", 40000 if fmt in {"wav", "pcm"} else 48000 if fmt == "ogg_opus" else 44100)
     if fmt not in FORMATS:
-        errors.append(f"format must be one of {sorted(FORMATS)}.")
-
-    sample_rate = payload.get("sample_rate")
-    if sample_rate not in SAMPLE_RATES:
-        errors.append(f"sample_rate must be one of {sorted(SAMPLE_RATES)}.")
-
-    audio_refs = payload.get("audio_references")
-    image_urls = payload.get("image_urls")
-    if audio_refs and image_urls:
-        errors.append("audio_references and image_urls are mutually exclusive.")
-    if audio_refs is not None:
-        if not isinstance(audio_refs, list):
-            errors.append("audio_references must be a list.")
-        elif len(audio_refs) > 3:
-            errors.append("audio_references supports at most 3 items.")
-    if image_urls is not None:
-        if not isinstance(image_urls, list):
-            errors.append("image_urls must be a list.")
-        elif len(image_urls) > 1:
-            errors.append("image_urls supports at most 1 item.")
-
-    for key in ("speech_rate", "loudness_rate"):
-        if key in payload:
-            value = payload[key]
-            if not isinstance(value, (int, float)) or value < 0.5 or value > 2:
-                errors.append(f"{key} must be between 0.5 and 2.0.")
-    if "pitch_rate" in payload:
-        value = payload["pitch_rate"]
-        if not isinstance(value, int) or value < -12 or value > 12:
-            errors.append("pitch_rate must be an integer between -12 and 12.")
+        errors.append("Unsupported audio format.")
+    if type(rate) is not int or rate not in SAMPLE_RATES or (fmt == "mp3" and rate == 40000) or (fmt == "ogg_opus" and rate != 48000):
+        errors.append("sample_rate is incompatible with the output format.")
+    for name, low, high in [("speech_rate", -50, 100), ("loudness_rate", -50, 100), ("pitch_rate", -12, 12)]:
+        if name in config and (type(config[name]) is not int or not low <= config[name] <= high):
+            errors.append(f"{name} must be an integer in [{low}, {high}].")
+    if "enable_subtitle" in config and type(config["enable_subtitle"]) is not bool:
+        errors.append("enable_subtitle must be boolean.")
+    refs = payload.get("references", [])
+    if not isinstance(refs, list):
+        errors.append("references must be a list.")
+        refs = []
+    audio, image = 0, 0
+    for ref in refs:
+        if not isinstance(ref, dict) or len(ref) != 1:
+            errors.append("Each reference must contain exactly one source field.")
+            continue
+        key, value = next(iter(ref.items()))
+        if key not in {"speaker", "audio_data", "audio_url", "image_data", "image_url"} or not isinstance(value, str) or not value.strip():
+            errors.append("Unsupported or empty reference.")
+            continue
+        image += int(key.startswith("image"))
+        audio += int(not key.startswith("image"))
+        if key.endswith("_url"):
+            u = urlparse(value)
+            if u.scheme not in {"http", "https"} or not u.hostname or u.username or u.password:
+                errors.append("Reference URL must be an HTTP(S) URL without credentials.")
+        if key.endswith("_data"):
+            try:
+                size = len(base64.b64decode(value, validate=True))
+                if not 0 < size <= 10 * 1024 * 1024:
+                    raise ValueError()
+            except ValueError:
+                errors.append("Reference base64 must decode to 1 byte–10 MiB.")
+    if audio and image:
+        errors.append("Audio and image references are mutually exclusive.")
+    if audio > 3 or image > 1:
+        errors.append("Use up to three audio references or one image reference.")
+    watermark = payload.get("watermark", {})
+    if not isinstance(watermark, dict):
+        errors.append("watermark must be an object.")
+    else:
+        if set(watermark) - {"aigc_watermark", "aigc_metadata"}:
+            errors.append("Unsupported watermark fields.")
+        if "aigc_watermark" in watermark and type(watermark["aigc_watermark"]) is not bool:
+            errors.append("aigc_watermark must be boolean.")
+        meta = watermark.get("aigc_metadata", {})
+        if not isinstance(meta, dict) or set(meta) - {"enable", "content_producer", "produce_id", "content_propagator", "propagate_id"}:
+            errors.append("Invalid aigc_metadata.")
+        elif any(type(v) is not bool if k == "enable" else not isinstance(v, str) for k, v in meta.items()):
+            errors.append("Invalid watermark metadata field type.")
     return errors
 
 
-def request_hash(payload: dict[str, Any]) -> str:
+def request_hash(payload):
     data = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
-    return hashlib.sha256(data).hexdigest()[:16]
+    return hashlib.sha256(data).hexdigest()

package/seedaudiocli.config.example.json

@@ -1,7 +1,7 @@
 {
   "SEEDAUDIO_API_KEY": "",
-  "SEEDAUDIO_BASE_URL": "https://api.evolink.ai",
-  "SEEDAUDIO_MODEL": "doubao-seed-audio-1-0",
+  "SEEDAUDIO_BASE_URL": "https://openspeech.bytedance.com",
+  "SEEDAUDIO_MODEL": "seed-audio-1.0",
   "SEEDAUDIO_DEFAULT_FORMAT": "mp3",
   "SEEDAUDIO_DEFAULT_SAMPLE_RATE": "44100"
 }

package/seedaudiocli.env.example

@@ -4,7 +4,7 @@
 # This is a local-only file. Do not commit real API keys.
 
 SEEDAUDIO_API_KEY=
-SEEDAUDIO_BASE_URL=https://api.evolink.ai
-SEEDAUDIO_MODEL=doubao-seed-audio-1-0
+SEEDAUDIO_BASE_URL=https://openspeech.bytedance.com
+SEEDAUDIO_MODEL=seed-audio-1.0
 SEEDAUDIO_DEFAULT_FORMAT=mp3
 SEEDAUDIO_DEFAULT_SAMPLE_RATE=44100

package/skills/seedaudiocli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: seedaudiocli
-description: Generate audio through EvoLink Seed Audio using the seedaudiocli CLI; import configuration files, submit explicit audio requests, recover tasks, and download results.
+description: Generate audio through official Volcengine Seed Audio using the seedaudiocli CLI; import configuration files, submit explicit audio requests, recover tasks, and download results.
 ---
 
 # Seed Audio CLI
@@ -10,7 +10,9 @@ Inputs are an explicit audio prompt, selected reference mode, output settings an
 
 ## Runtime and discovery
 
-Requires Node.js 22+, Python 3.9+ with SSL, network access to EvoLink, and an authorized API key. Run `seedaudiocli version`, `seedaudiocli capabilities --json` and `seedaudiocli doctor --json`. Resolve the canonical Skill with `seedaudiocli skill source --json`; the returned `source` directory belongs to the installed npm package.
+Requires Node.js 22+, Python 3.9+ with SSL, network access to Doubao Speech, and an authorized API key. Run `seedaudiocli version`, `seedaudiocli capabilities --json` and `seedaudiocli doctor --json`. Resolve the canonical Skill with `seedaudiocli skill source --json`; the returned `source` directory belongs to the installed npm package.
+
+When continuing an existing conversation or after a package update, load the current canonical `SKILL.md` and read the selected leaf command's `--help` (for example, `seedaudiocli generate text --help`). Build the invocation from that live contract; earlier conversation commands may belong to a different version.
 
 Use the current host's terminal execution capability. Its mapping is declared in [capabilities.json](capabilities.json) and the selected adapter: [Codex](adapters/codex.json) or [SealSeek](adapters/sealseek.json). Adapter mappings are implemented; host integration evidence is separate from CLI tests.
 
@@ -18,34 +20,44 @@ Use the current host's terminal execution capability. Its mapping is declared in
 
 1. Check `seedaudiocli auth status`. This checks local configuration only and does not prove the key is accepted remotely.
 2. If configuration is missing, ask the user for the local path to the administrator-provided JSON or env configuration file. Import with `seedaudiocli config import "FILE"`. Pass the file path to the CLI without displaying or reading its secret contents into the conversation. If configuration already exists, preserve it; an explicitly requested replacement uses `--replace`, which creates a backup. After import, return to step 1. Interactive terminal users can run `seedaudiocli setup`.
-3. Preserve the caller's prompt, model, reference mode and output choices. Choose `generate text`, `generate audio-ref`, or `generate image-ref` according to those inputs. Prompts support at most 1500 characters; audio mode accepts up to three preset IDs or public audio URLs; image mode accepts exactly one public image URL. Local references need an authorized hosting step outside this CLI.
-4. Validate the intended request with `--dry-run`. Validation must succeed before paid submission. Configuration import and dry-run do not submit generation jobs.
-5. Execute the authorized request with `--wait --download "OUTPUT_DIRECTORY"` when local delivery is required. Save the returned task ID. Generation can incur service charges.
+3. Preserve the caller's prompt, model, reference mode and output choices. Choose `generate text`, `generate audio-ref`, or `generate image-ref` according to those inputs. Prompts support 1–3000 characters. Audio mode accepts up to three preset speaker IDs, public URLs or local recordings (each at most 30 seconds and 10 MiB). Image mode accepts one JPEG/PNG/WebP URL or local image (at most 10 MiB). Use `--audio-file` / `--image-file` for local files; the CLI sends their bytes directly. Audio and image references are mutually exclusive.
+4. Construct the complete generation command, including references, output settings, timeout, destination and output name. Validate that exact command by adding `--dry-run`; after success, remove only `--dry-run` for the authorized submission. If any argument changes, repeat this preflight. Configuration import and dry-run do not submit generation jobs.
+5. Execute the authorized request with `--download "OUTPUT_DIRECTORY"` when local delivery is required. The official call is synchronous; `--wait` remains a compatibility flag. Save the local task ID emitted before submission. The CLI saves the official response and audio in private local state. Generation can incur service charges.
 6. Inspect status and actual output paths. A completed task without an audio file is incomplete delivery. Report the task ID, file and material limitations; content quality remains the caller's acceptance responsibility.
 
 ## Invocation examples
 
 ```bash
-seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --dry-run
-seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --wait --download ./audio
-seedaudiocli generate audio-ref --audio-reference zh_female_vv_uranus_bigtts --prompt "@audio1 今天的咖啡刚刚好。" --wait --download ./audio
+seedaudiocli generate text --help
+seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --timeout 300 --download ./audio --output-name piano --dry-run
+seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --timeout 300 --download ./audio --output-name piano
+seedaudiocli generate audio-ref --audio-reference zh_female_vv_uranus_bigtts --prompt "@音频1 今天的咖啡刚刚好。" --wait --download ./audio
 seedaudiocli generate image-ref --image-url "https://example.com/reference.jpg" --prompt "Generate audio matching the supplied reference." --dry-run
 seedaudiocli task get TASK_ID
 seedaudiocli task wait TASK_ID --download ./audio
 seedaudiocli task jobs --limit 20
 ```
 
-Use `@audio1` through `@audio3` in prompts to address the corresponding audio references. Supported formats are mp3, wav, pcm and ogg_opus. Use the command help for sample-rate and other constraints. Explicit unsupported requests require caller resolution.
+Use `@音频1` through `@音频3` to address references in order; `--audio-reference` entries precede `--audio-file` entries when mixed. Supported formats are mp3, wav, pcm and ogg_opus. Sample rates are 8000, 16000, 24000, 32000, 40000, 44100 and 48000; mp3 excludes 40000, and ogg_opus requires 48000. Speech/loudness adjustments are integers from -50 to 100 (0 unchanged); pitch is an integer from -12 to 12. `--subtitle` saves returned subtitle JSON. For advanced official watermark fields use a JSON payload with `payload validate` then `payload submit`. Explicit unsupported requirements return to the caller.
+
+The only provider endpoint is `https://openspeech.bytedance.com/api/v3/tts/create`, with model `seed-audio-1.0` and `X-Api-Key` authentication. Use a Doubao Speech API key authorized for Seed Audio. Ark credentials belong to another service. The official schema is documented at https://docs.volcengine.com/docs/DoubaoVoice/audio-generation-http?lang=zh.
+
+Official generation waits synchronously for the HTTP response. `--timeout` sets the request timeout in seconds; `--wait` is an optional compatibility flag. `--interval` is unsupported because there is no remote polling loop. When migrating an old invocation, omit `--interval` and its value while preserving the caller's supported choices; it is not a substitute for `--timeout`.
 
 ## Error and recovery branches
 
+- Argument parsing error (`unrecognized arguments`, exit 2): read the selected command's current help, correct the invocation and return to step 4. A confirmed local parser rejection happens before audio submission, so it does not require `--force`. This branch applies only to a parser error; timeout, connection loss or a returned task ID require the recovery branches below. Inspect the CLI exit status and stderr directly; a following shell command can mask its exit status.
 - `CONFIG_REQUIRED`: request the file path, import, then return to authentication check.
 - `CONFIG_INVALID` or `CONFIG_READ_FAILED`: request a corrected file/path. Preserve the saved configuration.
 - `CONFIG_EXISTS`: explain that configuration already exists; replace only when the user requests it.
-- `AUTH_REQUIRED`: the provider rejected credentials or permissions. Request a valid replacement or account correction, then resume the same intended operation.
+- `CONFIG_MIGRATION_REQUIRED`: import the administrator-provided official configuration with authorized `--replace`; a backup preserves the previous file. Return to step 1.
+- `AUTH_REQUIRED`: credentials were rejected. Request a valid Doubao Speech replacement, then return to step 1. `PERMISSION_REQUIRED` means the account needs service permission correction.
 - `PYTHON_REQUIRED`: install a supported Python runtime in the host's managed environment; verify with `doctor` before returning to the main flow.
-- Network failure or polling timeout: retain configuration and recover using the existing task ID. Do not submit a duplicate paid job to fix a polling error.
-- Unknown submission outcome: inspect task history and provider evidence before any new explicitly authorized submission. `--force` intentionally bypasses local request deduplication and can charge again.
+- `task get`, `task wait` and `task download` read local records and saved responses; they make no remote polling call and need no API key. Completed saved audio can be exported again even if the provider URL expires.
+- Network timeout or interrupted submission: keep the local ID and inspect `task get`. If no successful response was saved, the outcome remains unknown; the official API has no task-query operation.
+- `REQUEST_BUSY`: an identical request is active or its process was interrupted. Inspect history and verify no process is still using the lock before removing a stale local lock. Resume local recovery first.
+- `OUTPUT_EXISTS`: choose a new output name or directory; reuse the saved result without another paid call. `OUTPUT_CONTRACT_FAILED`: inspect the saved response and report incomplete delivery.
+- `SUBMISSION_UNKNOWN`: inspect local history and provider billing/support evidence before any new explicitly authorized submission. `--force` intentionally bypasses local request deduplication and can charge again.
 - Provider failure: report it with the task ID. Changing prompt, references or model is a caller decision.
 
 ## Installation and update

package/skills/seedaudiocli/capabilities.json

@@ -33,7 +33,13 @@
         "CONFIG_INVALID",
         "AUTH_REQUIRED",
         "PYTHON_REQUIRED",
-        "PROVIDER_FAILURE"
+        "PROVIDER_FAILURE",
+        "CONFIG_MIGRATION_REQUIRED",
+        "PERMISSION_REQUIRED",
+        "SUBMISSION_UNKNOWN",
+        "REQUEST_BUSY",
+        "OUTPUT_CONTRACT_FAILED",
+        "OUTPUT_EXISTS"
       ]
     }
   ]

package/seedaudiocli/evolink.py

@@ -1,149 +0,0 @@
-from __future__ import annotations
-
-import json
-import re
-import time
-import urllib.error
-import urllib.request
-from pathlib import Path
-from typing import Any
-
-from .config import seedaudio_api_key, seedaudio_base_url
-
-
-class SeedAudioError(RuntimeError):
-    def __init__(self, message: str, code: str = "PROVIDER_FAILURE"):
-        super().__init__(message)
-        self.code = code
-
-
-def _headers(json_body: bool = True) -> dict[str, str]:
-    key = seedaudio_api_key()
-    if not key:
-        raise SeedAudioError("Run seedaudiocli setup to import a configuration file.", "CONFIG_REQUIRED")
-    headers = {"Authorization": f"Bearer {key}"}
-    if json_body:
-        headers["Content-Type"] = "application/json"
-    return headers
-
-
-def api_root() -> str:
-    return seedaudio_base_url()
-
-
-def create_url() -> str:
-    return f"{api_root()}/v1/audios/generations"
-
-
-def task_url(task_id: str) -> str:
-    return f"{api_root()}/v1/tasks/{task_id}"
-
-
-def _request(method: str, url: str, body: dict[str, Any] | None = None, timeout: int = 120) -> dict[str, Any]:
-    data = json.dumps(body, ensure_ascii=False).encode("utf-8") if body is not None else None
-    req = urllib.request.Request(url, data=data, headers=_headers(json_body=body is not None), method=method)
-    try:
-        with urllib.request.urlopen(req, timeout=timeout) as resp:
-            text = resp.read().decode("utf-8")
-            if not text:
-                return {}
-            return json.loads(text)
-    except urllib.error.HTTPError as e:
-        text = e.read().decode("utf-8", errors="replace")
-        if e.code in {401, 403}:
-            raise SeedAudioError("Provider rejected authorization. Check key validity and account permissions.", "AUTH_REQUIRED") from e
-        raise SeedAudioError(f"HTTP {e.code}: {text}") from e
-    except urllib.error.URLError as e:
-        raise SeedAudioError(f"Network error: {e}") from e
-    except json.JSONDecodeError as e:
-        raise SeedAudioError(f"Non-JSON response from EvoLink: {e}") from e
-
-
-def _request_with_retry(method: str, url: str, body: dict[str, Any] | None = None, timeout: int = 120) -> dict[str, Any]:
-    last_error: SeedAudioError | None = None
-    for attempt in range(1, 4):
-        try:
-            return _request(method, url, body, timeout)
-        except SeedAudioError as e:
-            last_error = e
-            if attempt < 3:
-                time.sleep(min(2 * attempt, 8))
-    raise last_error or SeedAudioError("Request failed")
-
-
-def create_task(payload: dict[str, Any]) -> dict[str, Any]:
-    return _request("POST", create_url(), payload)
-
-
-def get_task(task_id: str) -> dict[str, Any]:
-    return _request_with_retry("GET", task_url(task_id), None, timeout=60)
-
-
-def extract_task_id(response: dict[str, Any]) -> str | None:
-    for key in ("id", "task_id", "taskId"):
-        value = response.get(key)
-        if value:
-            return str(value)
-    return None
-
-
-def extract_status(response: dict[str, Any]) -> str:
-    value = response.get("status")
-    return str(value).lower() if value else "unknown"
-
-
-def extract_audio_urls(response: dict[str, Any]) -> list[str]:
-    urls: list[str] = []
-    result_data = response.get("result_data")
-    if isinstance(result_data, list):
-        for item in result_data:
-            if isinstance(item, dict):
-                value = item.get("audio_url")
-                if isinstance(value, str) and value.startswith(("http://", "https://")):
-                    urls.append(value)
-    results = response.get("results")
-    if isinstance(results, list):
-        for value in results:
-            if isinstance(value, str) and value.startswith(("http://", "https://")):
-                urls.append(value)
-    seen: list[str] = []
-    for url in urls:
-        if url not in seen:
-            seen.append(url)
-    return seen
-
-
-def infer_extension(url: str, output_format: str | None = None) -> str:
-    match = re.search(r"\.(mp3|wav|ogg|opus|pcm)(\?|$)", url, re.I)
-    if match:
-        ext = match.group(1).lower()
-        return "ogg_opus" if ext == "opus" else ext
-    return output_format or "mp3"
-
-
-def wait_for_task(task_id: str, interval: int = 5, timeout: int = 1800) -> dict[str, Any]:
-    deadline = time.time() + timeout
-    last_response: dict[str, Any] = {}
-    while time.time() < deadline:
-        last_response = get_task(task_id)
-        status = extract_status(last_response)
-        if status in {"completed", "failed", "cancelled", "canceled", "expired"}:
-            return last_response
-        time.sleep(interval)
-    raise SeedAudioError(f"Timed out waiting for task {task_id}. Last response: {json.dumps(last_response, ensure_ascii=False)}")
-
-
-def download_url(url: str, out: Path) -> Path:
-    out.parent.mkdir(parents=True, exist_ok=True)
-    req = urllib.request.Request(url, headers={"User-Agent": "seedaudiocli/0.1"})
-    last_error: urllib.error.URLError | None = None
-    for attempt in range(1, 4):
-        try:
-            with urllib.request.urlopen(req, timeout=300) as resp:
-                out.write_bytes(resp.read())
-            return out
-        except urllib.error.URLError as e:
-            last_error = e
-            if attempt < 3:
-                time.sleep(min(2 * attempt, 8))
-    raise SeedAudioError(f"Download failed: {last_error}") from last_error