@petercjl/seedaudiocli 0.0.0-bootstrap.0 → 0.1.1

package/seedaudiocli/cli.py

@@ -0,0 +1,386 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+from . import __version__
+from . import evolink
+from .config import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MODEL,
+    config_path,
+    job_store_path,
+    seedaudio_api_key,
+    seedaudio_base_url,
+    seedaudio_model,
+    write_default_env,
+    import_config,
+    ConfigError,
+)
+from .jobs import append_job, append_status, find_by_hash, read_jobs
+from .payloads import build_payload, read_prompt, request_hash, validate_payload
+
+
+def print_json(data: Any) -> None:
+    print(json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True))
+
+
+def add_generation_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--prompt", help="Prompt text, max 1500 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("--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("--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("--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("--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.")
+
+
+def generation_payload_from_args(args: argparse.Namespace) -> dict[str, Any]:
+    prompt = read_prompt(args.prompt, args.prompt_file)
+    audio_refs = list(getattr(args, "audio_reference", None) or [])
+    image_urls = list(getattr(args, "image_url", None) or [])
+    return build_payload(
+        prompt=prompt,
+        model=args.model,
+        audio_references=audio_refs,
+        image_urls=image_urls,
+        output_format=args.format,
+        sample_rate=args.sample_rate,
+        speech_rate=args.speech_rate,
+        loudness_rate=args.loudness_rate,
+        pitch_rate=args.pitch_rate,
+        callback_url=args.callback_url,
+    )
+
+
+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:
+    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)
+        return 2
+    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})
+        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
+        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
+
+
+def cmd_config(args: argparse.Namespace) -> int:
+    if args.config_cmd == "import":
+        print_json(import_config(args.file, replace=args.replace))
+        return 0
+    if args.config_cmd == "path":
+        print(str(config_path()))
+        return 0
+    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}")
+        return 0
+    raise SystemExit("unknown config command")
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    if args.file:
+        print_json(import_config(args.file, replace=args.replace))
+        return 0
+    if seedaudio_api_key():
+        print_json({"ok": True, "configured": True, "config_path": str(config_path()), "remote_verified": False})
+        return 0
+    if not sys.stdin.isatty():
+        raise ConfigError("CONFIG_REQUIRED", "Ask the user for the configuration file path, then run seedaudiocli config import FILE.")
+    print("请输入管理员提供的配置文件路径（文件内容不会显示）：", file=sys.stderr)
+    source = input().strip().strip('"').strip("'")
+    if not source:
+        raise ConfigError("CONFIG_REQUIRED", "A configuration file path is required.")
+    print_json(import_config(source, replace=args.replace))
+    return 0
+
+
+def cmd_auth(args: argparse.Namespace) -> int:
+    key = seedaudio_api_key()
+    data: dict[str, Any] = {
+        "ok": bool(key),
+        "config_path": str(config_path()),
+        "base_url": seedaudio_base_url(),
+        "model": seedaudio_model(),
+        "api_key_source": "process-env" if os.environ.get("SEEDAUDIO_API_KEY") else ("config-file" if key else "missing"),
+        "api_key_present": bool(key),
+        "remote_verified": False,
+    }
+    if args.check_remote and key:
+        payload = build_payload(
+            prompt="Generate one second of quiet neutral test audio. No vocals.",
+            output_format="mp3",
+            sample_rate=44100,
+        )
+        data["remote_payload_valid"] = not validate_payload(payload)
+        data["remote_check_note"] = "Use `generate text --wait --download` for a live billing test."
+    print_json(data)
+    return 0 if key else 1
+
+
+def cmd_models(_: argparse.Namespace) -> int:
+    print_json(
+        {
+            "default": DEFAULT_MODEL,
+            "configured": seedaudio_model(),
+            "base_url_default": DEFAULT_BASE_URL,
+            "notes": "EvoLink currently exposes doubao-seed-audio-1-0 for this CLI.",
+        }
+    )
+    return 0
+
+
+def cmd_generate(args: argparse.Namespace) -> int:
+    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
+    if args.task_cmd == "jobs":
+        print_json({"job_store": str(job_store_path()), "jobs": read_jobs()[-args.limit :]})
+        return 0
+    raise SystemExit("unknown task command")
+
+
+def cmd_payload(args: argparse.Namespace) -> int:
+    payload = json.loads(Path(args.file).expanduser().read_text(encoding="utf-8"))
+    if args.payload_cmd == "validate":
+        errors = validate_payload(payload)
+        print_json({"ok": not errors, "errors": errors})
+        return 0 if not errors else 2
+    if args.payload_cmd == "print":
+        print_json(payload)
+        return 0
+    if args.payload_cmd == "submit":
+        submit_args = SimpleNamespace(
+            dry_run=False,
+            force=args.force,
+            wait=args.wait,
+            interval=args.interval,
+            timeout=args.timeout,
+            download=args.download,
+            output_name=args.output_name,
+        )
+        return submit_or_print(payload, submit_args)
+    raise SystemExit("unknown payload command")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="seedaudiocli", description="System CLI for EvoLink Doubao Seed-Audio 1.0 generation.")
+    parser.add_argument("--version", action="version", version=f"seedaudiocli {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    setup = sub.add_parser("setup", help="Import credentials once, or prompt for a configuration file path.")
+    setup.add_argument("--file")
+    setup.add_argument("--replace", action="store_true", help="Back up existing configuration before replacement.")
+    setup.set_defaults(func=cmd_setup)
+
+    config = sub.add_parser("config", help="Manage local env config.")
+    config_sub = config.add_subparsers(dest="config_cmd", required=True)
+    config_sub.add_parser("path", help="Print env config path.")
+    config_import = config_sub.add_parser("import", help="Import a JSON or KEY=value configuration file.")
+    config_import.add_argument("file")
+    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)
+
+    auth = sub.add_parser("auth", help="Check auth configuration.")
+    auth_sub = auth.add_subparsers(dest="auth_cmd", required=True)
+    status = auth_sub.add_parser("status", help="Show auth status without printing secrets.")
+    status.add_argument("--check-remote", action="store_true", help="Validate a remote-check payload without billing.")
+    status.set_defaults(func=cmd_auth)
+
+    models = sub.add_parser("models", help="Model helpers.")
+    models_sub = models.add_subparsers(dest="models_cmd", required=True)
+    models_list = models_sub.add_parser("list", help="List built-in model ids.")
+    models_list.set_defaults(func=cmd_models)
+
+    generate = sub.add_parser("generate", help="Create Seed-Audio generation tasks.")
+    gen_sub = generate.add_subparsers(dest="generate_cmd", required=True)
+
+    gen_text = gen_sub.add_parser("text", help="Text-to-audio generation.")
+    add_generation_args(gen_text)
+    gen_text.set_defaults(func=cmd_generate)
+
+    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.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.set_defaults(func=cmd_generate)
+
+    task = sub.add_parser("task", help="Task status, wait, URLs, and history.")
+    task_sub = task.add_subparsers(dest="task_cmd", required=True)
+    task_get = task_sub.add_parser("get", help="Fetch raw task JSON.")
+    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.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_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")
+    task_url.set_defaults(func=cmd_task)
+
+    task_jobs = task_sub.add_parser("jobs", help="Show local task history.")
+    task_jobs.add_argument("--limit", type=int, default=20)
+    task_jobs.set_defaults(func=cmd_task)
+
+    payload = sub.add_parser("payload", help="Validate or submit raw JSON payloads.")
+    payload_sub = payload.add_subparsers(dest="payload_cmd", required=True)
+    payload_validate = payload_sub.add_parser("validate")
+    payload_validate.add_argument("file")
+    payload_validate.set_defaults(func=cmd_payload)
+    payload_print = payload_sub.add_parser("print")
+    payload_print.add_argument("file")
+    payload_print.set_defaults(func=cmd_payload)
+    payload_submit = payload_sub.add_parser("submit")
+    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("--download")
+    payload_submit.add_argument("--output-name")
+    payload_submit.set_defaults(func=cmd_payload)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    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():
+                cmd_setup(SimpleNamespace(file=None, replace=False))
+            else:
+                raise ConfigError("CONFIG_REQUIRED", "Ask the user for the configuration file path, then run seedaudiocli config import FILE.")
+        return int(args.func(args))
+    except ConfigError as e:
+        print_json({"ok": False, "code": e.code, "error": str(e)})
+        return 2
+    except (ValueError, evolink.SeedAudioError) as e:
+        message = str(e)
+        try:
+            key = seedaudio_api_key()
+            if key:
+                message = message.replace(key, "[REDACTED]")
+        except ConfigError:
+            pass
+        print_json({"ok": False, "code": getattr(e, "code", "REQUEST_FAILED"), "error": message})
+        return 1
+    except (OSError, EOFError, KeyboardInterrupt):
+        print_json({"ok": False, "code": "LOCAL_OPERATION_FAILED", "error": "Local operation failed or was cancelled."})
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/seedaudiocli/config.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+import os
+import json
+import stat
+import tempfile
+import uuid
+from pathlib import Path
+from urllib.parse import urlparse
+
+
+APP_NAME = "seedaudiocli"
+DEFAULT_BASE_URL = "https://api.evolink.ai"
+DEFAULT_MODEL = "doubao-seed-audio-1-0"
+DEFAULT_FORMAT = "mp3"
+DEFAULT_SAMPLE_RATE = "44100"
+
+
+def home() -> Path:
+    return Path.home()
+
+
+def config_dir() -> Path:
+    if os.environ.get("SEEDAUDIO_CONFIG_DIR"):
+        return Path(os.environ["SEEDAUDIO_CONFIG_DIR"]).expanduser()
+    if os.name == "nt":
+        return Path(os.environ.get("APPDATA", home() / "AppData" / "Roaming")) / APP_NAME
+    return home() / ".config" / APP_NAME
+
+
+def config_path() -> Path:
+    return config_dir() / "seedaudiocli.env"
+
+
+def state_dir() -> Path:
+    if os.environ.get("SEEDAUDIO_STATE_DIR"):
+        return Path(os.environ["SEEDAUDIO_STATE_DIR"]).expanduser()
+    if os.name == "nt":
+        return Path(os.environ.get("LOCALAPPDATA", home() / "AppData" / "Local")) / APP_NAME
+    return home() / ".local" / "state" / APP_NAME
+
+
+class ConfigError(ValueError):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+ALLOWED = {"SEEDAUDIO_API_KEY", "SEEDAUDIO_BASE_URL", "SEEDAUDIO_MODEL",
+           "SEEDAUDIO_DEFAULT_FORMAT", "SEEDAUDIO_DEFAULT_SAMPLE_RATE"}
+
+
+def validate_config(values: dict[str, str], require_key: bool = True) -> dict[str, str]:
+    if not isinstance(values, dict) or set(values) - ALLOWED:
+        raise ConfigError("CONFIG_INVALID", "Configuration contains unsupported fields.")
+    if any(not isinstance(v, str) or any(ord(c) < 32 for c in v) for v in values.values()):
+        raise ConfigError("CONFIG_INVALID", "Configuration values must be single-line strings.")
+    key = values.get("SEEDAUDIO_API_KEY", "").strip()
+    if require_key and (not key or key.lower() in {"your-api-key", "replace-me", "changeme"}):
+        raise ConfigError("CONFIG_INVALID", "A non-empty API key is required.")
+    if key and (any(c.isspace() for c in key) or not key.isascii()):
+        raise ConfigError("CONFIG_INVALID", "API key must contain only non-space ASCII characters.")
+    base = values.get("SEEDAUDIO_BASE_URL", DEFAULT_BASE_URL)
+    try:
+        parsed = urlparse(base)
+        valid_url = parsed.scheme == "https" and parsed.hostname and not (parsed.username or parsed.password or parsed.query or parsed.fragment)
+        parsed.port
+    except ValueError:
+        valid_url = False
+    if not valid_url:
+        raise ConfigError("CONFIG_INVALID", "API base URL must be HTTPS without credentials, query or fragment.")
+    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"}:
+        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.")
+    return {**values, "SEEDAUDIO_API_KEY": key}
+
+
+def parse_config_text(text: str, require_key: bool = True) -> dict[str, str]:
+    if text.lstrip().startswith("{"):
+        try:
+            values = json.loads(text)
+        except (ValueError, TypeError):
+            raise ConfigError("CONFIG_INVALID", "Invalid JSON configuration.") from None
+        return validate_config(values, require_key=require_key)
+    values = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            raise ConfigError("CONFIG_INVALID", "Expected KEY=value configuration data.")
+        key, value = line.split("=", 1)
+        key, value = key.strip(), value.strip()
+        if len(value) >= 2 and value[0] in "\"'" and value[-1] == value[0]:
+            value = value[1:-1]
+        if key in values:
+            raise ConfigError("CONFIG_INVALID", "Duplicate configuration field.")
+        values[key] = value
+    return validate_config(values, require_key=require_key)
+
+
+def save_config(values: dict[str, str], replace: bool = False, require_key: bool = True) -> dict:
+    values = validate_config(values, require_key=require_key)
+    target = config_path()
+    if target.is_symlink() or (target.exists() and not target.is_file()):
+        raise ConfigError("CONFIG_UNSAFE_TARGET", "Configuration target must be a regular file.")
+    if target.exists() and not replace:
+        raise ConfigError("CONFIG_EXISTS", "Configuration already exists; use --replace to back it up and replace it.")
+    target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    lock = target.parent / ".config-import.lock"
+    try:
+        lock_fd = os.open(lock, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError:
+        raise ConfigError("CONFIG_BUSY", "Another configuration import holds the lock.") from None
+    backup = None
+    temp = None
+    try:
+        os.close(lock_fd)
+        if target.is_symlink() or (target.exists() and not target.is_file()):
+            raise ConfigError("CONFIG_UNSAFE_TARGET", "Configuration target must be a regular file.")
+        if target.exists():
+            if not replace:
+                raise ConfigError("CONFIG_EXISTS", "Configuration already exists; use --replace.")
+            backup = target.with_name(target.name + ".backup-" + uuid.uuid4().hex)
+            with open(backup, "xb") as out:
+                os.chmod(backup, 0o600)
+                out.write(target.read_bytes())
+        content = "\n".join(f"{k}={v}" for k, v in sorted(values.items())) + "\n"
+        fd, name = tempfile.mkstemp(prefix=".config-", dir=target.parent)
+        temp = Path(name)
+        with os.fdopen(fd, "w", encoding="utf-8") as out:
+            out.write(content)
+            out.flush()
+            os.fsync(out.fileno())
+        os.replace(temp, target)
+        os.chmod(target, 0o600)
+        return {"ok": True, "config_path": str(target), "backup": str(backup) if backup else None,
+                "api_key_present": bool(values.get("SEEDAUDIO_API_KEY")), "remote_verified": False}
+    finally:
+        if temp and temp.exists():
+            temp.unlink()
+        lock.unlink()
+
+
+def import_config(source: str, replace: bool = False) -> dict:
+    path = Path(source).expanduser()
+    try:
+        info = path.stat()
+        if not stat.S_ISREG(info.st_mode) or info.st_size > 65536:
+            raise ConfigError("CONFIG_INVALID", "Configuration must be a regular file under 64 KiB.")
+        values = parse_config_text(path.read_text(encoding="utf-8-sig"))
+    except (OSError, UnicodeError):
+        raise ConfigError("CONFIG_READ_FAILED", "Cannot read the configuration file as UTF-8.") from None
+    return save_config(values, replace=replace)
+
+
+def job_store_path() -> Path:
+    return state_dir() / "jobs.jsonl"
+
+
+def load_env_file(path: Path | None = None) -> dict[str, str]:
+    path = path or config_path()
+    if not path.exists():
+        return {}
+    try:
+        text = path.read_text(encoding="utf-8-sig")
+    except (OSError, UnicodeError):
+        raise ConfigError("CONFIG_READ_FAILED", "Cannot read saved configuration.") from None
+    return parse_config_text(text, require_key=False)
+
+
+def get_setting(name: str, default: str | None = None) -> str | None:
+    value = os.environ.get(name)
+    if value:
+        return value
+    return load_env_file().get(name, default)
+
+
+def seedaudio_api_key() -> str | None:
+    return get_setting("SEEDAUDIO_API_KEY")
+
+
+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("/")
+
+
+def seedaudio_model() -> str:
+    return get_setting("SEEDAUDIO_MODEL", DEFAULT_MODEL) or DEFAULT_MODEL
+
+
+def default_format() -> str:
+    return get_setting("SEEDAUDIO_DEFAULT_FORMAT", DEFAULT_FORMAT) or DEFAULT_FORMAT
+
+
+def default_sample_rate() -> int:
+    value = get_setting("SEEDAUDIO_DEFAULT_SAMPLE_RATE", DEFAULT_SAMPLE_RATE) or DEFAULT_SAMPLE_RATE
+    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()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists() and not overwrite:
+        return path
+
+    current_key = os.environ.get("SEEDAUDIO_API_KEY", "") if import_current_env else ""
+    current_base = os.environ.get("SEEDAUDIO_BASE_URL", DEFAULT_BASE_URL) if import_current_env else DEFAULT_BASE_URL
+    current_model = os.environ.get("SEEDAUDIO_MODEL", DEFAULT_MODEL) if import_current_env else DEFAULT_MODEL
+    current_format = os.environ.get("SEEDAUDIO_DEFAULT_FORMAT", DEFAULT_FORMAT) if import_current_env else DEFAULT_FORMAT
+    current_sample_rate = (
+        os.environ.get("SEEDAUDIO_DEFAULT_SAMPLE_RATE", DEFAULT_SAMPLE_RATE)
+        if import_current_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)
+    return path