acemusic-cli 2026.11.17.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1 @@
1
+ """AceMusic CLI - AI Music Generation via AceDataCloud API."""
@@ -0,0 +1,5 @@
1
+ """Allow running as python -m acemusic_cli."""
2
+
3
+ from acemusic_cli.main import cli
4
+
5
+ cli()
File without changes
@@ -0,0 +1,93 @@
1
+ """Paid music and lyrics submissions."""
2
+
3
+ from pathlib import Path
4
+ from typing import Any
5
+
6
+ import click
7
+
8
+ from acemusic_cli.core.client import get_client
9
+ from acemusic_cli.core.exceptions import AceMusicError
10
+ from acemusic_cli.core.output import print_json
11
+
12
+
13
+ @click.command()
14
+ @click.argument("prompt", required=False)
15
+ @click.option(
16
+ "--model",
17
+ type=click.Choice(["acemusic-v1.1", "acemusic-v1"]),
18
+ default="acemusic-v1.1",
19
+ show_default=True,
20
+ )
21
+ @click.option(
22
+ "--lyric-file",
23
+ type=click.Path(exists=True, dir_okay=False, path_type=Path),
24
+ help="UTF-8 custom lyrics file.",
25
+ )
26
+ @click.option("--style", help="Required with custom lyrics.")
27
+ @click.option("--title", default="")
28
+ @click.option("--callback-url", help="A real webhook you control.")
29
+ @click.option("--json", "output_json", is_flag=True, help="Print JSON (the default).")
30
+ @click.pass_context
31
+ def generate(
32
+ ctx: click.Context,
33
+ prompt: str | None,
34
+ model: str,
35
+ lyric_file: Path | None,
36
+ style: str | None,
37
+ title: str,
38
+ callback_url: str | None,
39
+ output_json: bool,
40
+ ) -> None:
41
+ """Submit ONE paid task targeting two song candidates, then save task_id.
42
+
43
+ Pass PROMPT for idea mode, or --lyric-file and --style for custom mode.
44
+ No automatic retry is made if submission times out.
45
+ """
46
+ del output_json
47
+ payload: dict[str, Any] = {
48
+ "action": "generate",
49
+ "model": model,
50
+ "custom": lyric_file is not None,
51
+ "async": True,
52
+ }
53
+ if lyric_file:
54
+ if prompt or not style:
55
+ raise click.UsageError("Custom mode requires --lyric-file and --style, without PROMPT.")
56
+ lyric = lyric_file.read_text(encoding="utf-8")
57
+ if not lyric.strip():
58
+ raise click.UsageError("The lyrics file is empty.")
59
+ payload.update(lyric=lyric, style=style)
60
+ if title:
61
+ payload["title"] = title
62
+ else:
63
+ if not prompt or style or title:
64
+ raise click.UsageError(
65
+ "Idea mode requires PROMPT; custom style/title require --lyric-file."
66
+ )
67
+ payload["prompt"] = prompt
68
+ if callback_url:
69
+ payload["callback_url"] = callback_url
70
+ try:
71
+ print_json(get_client(ctx.obj.get("token")).generate_audio(**payload))
72
+ except AceMusicError as error:
73
+ raise click.ClickException(
74
+ error.message + " Preserve the original request; do not automatically submit again."
75
+ ) from error
76
+
77
+
78
+ @click.command()
79
+ @click.argument("prompt")
80
+ @click.option("--style", default="")
81
+ @click.option("--json", "output_json", is_flag=True, help="Print JSON (the default).")
82
+ @click.pass_context
83
+ def lyrics(ctx: click.Context, prompt: str, style: str, output_json: bool) -> None:
84
+ """Generate lyrics and a title as a separately priced request."""
85
+ del output_json
86
+ try:
87
+ print_json(
88
+ get_client(ctx.obj.get("token")).generate_lyrics(
89
+ prompt=prompt, **({"style": style} if style else {})
90
+ )
91
+ )
92
+ except AceMusicError as error:
93
+ raise click.ClickException(error.message) from error
@@ -0,0 +1,147 @@
1
+ """Authenticated free task queries and explicit file download."""
2
+
3
+ import time
4
+ from pathlib import Path
5
+ from typing import Any
6
+ from urllib.parse import urlparse
7
+
8
+ import click
9
+ import httpx
10
+
11
+ from acemusic_cli.core.client import get_client
12
+ from acemusic_cli.core.exceptions import AceMusicError
13
+ from acemusic_cli.core.output import print_json
14
+
15
+ TERMINAL = {
16
+ "succeeded",
17
+ "complete",
18
+ "completed",
19
+ "partial_failed",
20
+ "failed",
21
+ "error",
22
+ "cancelled",
23
+ "canceled",
24
+ }
25
+ FAILURE = {"partial_failed", "failed", "error", "cancelled", "canceled"}
26
+
27
+
28
+ def task_state(result: dict[str, Any]) -> str:
29
+ state = str(result.get("state") or result.get("status") or "").lower()
30
+ if state in TERMINAL:
31
+ return state
32
+ response = result.get("response") or {}
33
+ if isinstance(response, dict):
34
+ response_state = str(response.get("state") or response.get("status") or "").lower()
35
+ if response_state in TERMINAL:
36
+ return response_state
37
+ if response.get("success") is False:
38
+ return "failed"
39
+ if response.get("success") is True and response.get("data"):
40
+ return "succeeded"
41
+ return state or "pending"
42
+
43
+
44
+ def query(ctx: click.Context, **payload: Any) -> dict[str, Any]:
45
+ try:
46
+ return get_client(ctx.obj.get("token")).query_task(**payload)
47
+ except AceMusicError as error:
48
+ raise click.ClickException(error.message) from error
49
+
50
+
51
+ @click.command()
52
+ @click.argument("task_id")
53
+ @click.option("--json", "output_json", is_flag=True)
54
+ @click.pass_context
55
+ def task(ctx: click.Context, task_id: str, output_json: bool) -> None:
56
+ """Retrieve the original task without generating again."""
57
+ del output_json
58
+ print_json(query(ctx, action="retrieve", id=task_id))
59
+
60
+
61
+ @click.command("tasks")
62
+ @click.argument("task_ids", nargs=-1, required=True)
63
+ @click.option("--json", "output_json", is_flag=True)
64
+ @click.pass_context
65
+ def tasks_batch(ctx: click.Context, task_ids: tuple[str, ...], output_json: bool) -> None:
66
+ """Retrieve up to 50 original task IDs."""
67
+ del output_json
68
+ if len(task_ids) > 50:
69
+ raise click.UsageError("At most 50 tasks per batch.")
70
+ print_json(query(ctx, action="retrieve_batch", ids=list(task_ids)))
71
+
72
+
73
+ @click.command()
74
+ @click.option("--page", type=click.IntRange(min=1), default=1)
75
+ @click.option("--page-size", type=click.IntRange(1, 50), default=20)
76
+ @click.pass_context
77
+ def history(ctx: click.Context, page: int, page_size: int) -> None:
78
+ """List your task history."""
79
+ print_json(query(ctx, action="list", limit=page_size, offset=(page - 1) * page_size))
80
+
81
+
82
+ @click.command()
83
+ @click.argument("task_id")
84
+ @click.option("--interval", type=click.FloatRange(min=1), default=10, show_default=True)
85
+ @click.option(
86
+ "--timeout", "max_timeout", type=click.FloatRange(min=1), default=600, show_default=True
87
+ )
88
+ @click.option("--json", "output_json", is_flag=True)
89
+ @click.pass_context
90
+ def wait(
91
+ ctx: click.Context, task_id: str, interval: float, max_timeout: float, output_json: bool
92
+ ) -> None:
93
+ """Wait a bounded time for the SAME task; retain its ID after timeout."""
94
+ del output_json
95
+ deadline = time.monotonic() + max_timeout
96
+ while True:
97
+ result = query(ctx, action="retrieve", id=task_id)
98
+ state = task_state(result)
99
+ if state in TERMINAL:
100
+ print_json(result)
101
+ if state in FAILURE:
102
+ raise click.exceptions.Exit(1)
103
+ return
104
+ remaining = deadline - time.monotonic()
105
+ if remaining <= 0:
106
+ raise click.ClickException(
107
+ f"Still pending. Resume with: acemusic wait {task_id}. No replacement was submitted."
108
+ )
109
+ time.sleep(min(interval, remaining))
110
+
111
+
112
+ @click.command()
113
+ @click.argument("task_id")
114
+ @click.option(
115
+ "--output",
116
+ type=click.Path(path_type=Path),
117
+ default=Path("."),
118
+ help="Destination directory; existing files are preserved.",
119
+ )
120
+ @click.pass_context
121
+ def download(ctx: click.Context, task_id: str, output: Path) -> None:
122
+ """Download final successful MP3 candidates from your original task."""
123
+ result = query(ctx, action="retrieve", id=task_id)
124
+ state = task_state(result)
125
+ if state not in TERMINAL:
126
+ raise click.ClickException("Task is still processing. Wait using the original task ID.")
127
+ response = result.get("response") or result
128
+ items = response.get("data", []) if isinstance(response, dict) else []
129
+ output.mkdir(parents=True, exist_ok=True)
130
+ count = 0
131
+ for index, item in enumerate(items, 1):
132
+ url = item.get("audio_url") if isinstance(item, dict) else None
133
+ if not url:
134
+ continue
135
+ parsed = urlparse(url)
136
+ if parsed.scheme != "https" or parsed.hostname != "cdn.acedata.cloud":
137
+ raise click.ClickException("Expected a final Ace Data Cloud CDN audio URL.")
138
+ target = output / f"{task_id}-{index}.mp3"
139
+ with httpx.stream("GET", url, follow_redirects=False, timeout=120) as stream:
140
+ stream.raise_for_status()
141
+ with target.open("xb") as file:
142
+ for chunk in stream.iter_bytes():
143
+ file.write(chunk)
144
+ click.echo(str(target))
145
+ count += 1
146
+ if not count:
147
+ raise click.ClickException("The terminal task contains no downloadable audio.")
@@ -0,0 +1 @@
1
+ """AceMusic CLI core modules."""
@@ -0,0 +1,112 @@
1
+ """HTTP client for AceMusic API."""
2
+
3
+ from typing import Any
4
+
5
+ import httpx
6
+
7
+ from acemusic_cli.core.config import settings
8
+ from acemusic_cli.core.exceptions import (
9
+ AceMusicAPIError,
10
+ AceMusicAuthError,
11
+ AceMusicTimeoutError,
12
+ )
13
+
14
+
15
+ class AceMusicClient:
16
+ """HTTP client for AceDataCloud AceMusic API."""
17
+
18
+ def __init__(self, api_token: str | None = None, base_url: str | None = None):
19
+ self.api_token = api_token if api_token is not None else settings.api_token
20
+ self.base_url = base_url or settings.api_base_url
21
+ self.timeout = settings.request_timeout
22
+
23
+ def _get_headers(self) -> dict[str, str]:
24
+ """Get request headers with authentication."""
25
+ if not self.api_token:
26
+ raise AceMusicAuthError("API token not configured")
27
+ return {
28
+ "accept": "application/json",
29
+ "authorization": f"Bearer {self.api_token}",
30
+ "content-type": "application/json",
31
+ }
32
+
33
+ def request(
34
+ self,
35
+ endpoint: str,
36
+ payload: dict[str, Any],
37
+ timeout: float | None = None,
38
+ ) -> dict[str, Any]:
39
+ """Make a POST request to the AceMusic API.
40
+
41
+ Args:
42
+ endpoint: API endpoint path
43
+ payload: Request body as dictionary
44
+ timeout: Optional timeout override
45
+
46
+ Returns:
47
+ API response as dictionary
48
+ """
49
+ url = f"{self.base_url}{endpoint}"
50
+ request_timeout = timeout or self.timeout
51
+
52
+ # Remove None values from payload
53
+ payload = {k: v for k, v in payload.items() if v is not None}
54
+
55
+ with httpx.Client() as http_client:
56
+ try:
57
+ response = http_client.post(
58
+ url,
59
+ json=payload,
60
+ headers=self._get_headers(),
61
+ timeout=request_timeout,
62
+ )
63
+
64
+ if response.status_code == 401:
65
+ raise AceMusicAuthError("Invalid API token")
66
+
67
+ if response.status_code == 403:
68
+ raise AceMusicAuthError("Access denied. Check your API permissions.")
69
+
70
+ response.raise_for_status()
71
+ return response.json() # type: ignore[no-any-return]
72
+
73
+ except httpx.TimeoutException as e:
74
+ raise AceMusicTimeoutError(
75
+ f"Request to {endpoint} timed out after {request_timeout}s"
76
+ ) from e
77
+
78
+ except AceMusicAuthError:
79
+ raise
80
+
81
+ except httpx.HTTPStatusError as e:
82
+ raise AceMusicAPIError(
83
+ message=e.response.text,
84
+ code=f"http_{e.response.status_code}",
85
+ status_code=e.response.status_code,
86
+ ) from e
87
+
88
+ except Exception as e:
89
+ if isinstance(e, AceMusicAPIError | AceMusicTimeoutError):
90
+ raise
91
+ raise AceMusicAPIError(message=str(e)) from e
92
+
93
+ # Convenience methods
94
+ def generate_audio(self, **kwargs: Any) -> dict[str, Any]:
95
+ """Generate audio using the audios endpoint."""
96
+ kwargs.setdefault("async", True)
97
+ return self.request("/acemusic/audios", kwargs)
98
+
99
+ def generate_lyrics(self, **kwargs: Any) -> dict[str, Any]:
100
+ """Generate lyrics using the lyrics endpoint."""
101
+ return self.request("/acemusic/lyrics", kwargs)
102
+
103
+ def query_task(self, **kwargs: Any) -> dict[str, Any]:
104
+ """Query task status using the tasks endpoint."""
105
+ return self.request("/acemusic/tasks", kwargs)
106
+
107
+
108
+ def get_client(token: str | None = None) -> AceMusicClient:
109
+ """Get a AceMusicClient instance, optionally overriding the token."""
110
+ if token:
111
+ return AceMusicClient(api_token=token)
112
+ return AceMusicClient()
@@ -0,0 +1,42 @@
1
+ """Configuration management for AceMusic CLI."""
2
+
3
+ import os
4
+ from dataclasses import dataclass, field
5
+
6
+ from dotenv import load_dotenv
7
+
8
+ load_dotenv()
9
+
10
+
11
+ @dataclass
12
+ class Settings:
13
+ """Application settings loaded from environment variables."""
14
+
15
+ api_base_url: str = field(
16
+ default_factory=lambda: os.environ.get(
17
+ "ACEDATACLOUD_API_BASE_URL", "https://api.acedata.cloud"
18
+ )
19
+ )
20
+ api_token: str = field(default_factory=lambda: os.environ.get("ACEDATACLOUD_API_TOKEN", ""))
21
+ request_timeout: float = field(
22
+ default_factory=lambda: float(os.environ.get("ACEMUSIC_REQUEST_TIMEOUT", "120"))
23
+ )
24
+ default_model: str = field(
25
+ default_factory=lambda: os.environ.get("ACEMUSIC_DEFAULT_MODEL", "acemusic-v1.1")
26
+ )
27
+
28
+ @property
29
+ def is_configured(self) -> bool:
30
+ """Check if the API token is configured."""
31
+ return bool(self.api_token)
32
+
33
+ def validate(self) -> None:
34
+ """Validate configuration. Raises ValueError if API token is missing."""
35
+ if not self.api_token:
36
+ raise ValueError(
37
+ "API token not configured. "
38
+ "Set ACEDATACLOUD_API_TOKEN environment variable or use --token option."
39
+ )
40
+
41
+
42
+ settings = Settings()
@@ -0,0 +1,37 @@
1
+ """Custom exceptions for AceMusic CLI."""
2
+
3
+
4
+ class AceMusicError(Exception):
5
+ """Base exception for AceMusic CLI."""
6
+
7
+ def __init__(self, message: str, code: str = "unknown"):
8
+ self.message = message
9
+ self.code = code
10
+ super().__init__(message)
11
+
12
+
13
+ class AceMusicAuthError(AceMusicError):
14
+ """Authentication error."""
15
+
16
+ def __init__(self, message: str = "Authentication failed"):
17
+ super().__init__(message, code="auth_error")
18
+
19
+
20
+ class AceMusicAPIError(AceMusicError):
21
+ """API error with HTTP status code."""
22
+
23
+ def __init__(
24
+ self,
25
+ message: str = "API request failed",
26
+ code: str = "api_error",
27
+ status_code: int | None = None,
28
+ ):
29
+ self.status_code = status_code
30
+ super().__init__(message, code)
31
+
32
+
33
+ class AceMusicTimeoutError(AceMusicError):
34
+ """Request timeout error."""
35
+
36
+ def __init__(self, message: str = "Request timed out"):
37
+ super().__init__(message, code="timeout_error")
@@ -0,0 +1,224 @@
1
+ """Rich terminal output formatting for AceMusic CLI."""
2
+
3
+ import json
4
+ from typing import Any
5
+
6
+ from rich.console import Console
7
+ from rich.panel import Panel
8
+ from rich.table import Table
9
+
10
+ console = Console()
11
+
12
+ # Available models
13
+ ACEMUSIC_MODELS = [
14
+ "acemusic-v1.1 Pro",
15
+ "acemusic-v1.1",
16
+ "acemusic-v1.1 Raw",
17
+ "FUZZ-1.1 Pro",
18
+ "FUZZ-1.0 Pro",
19
+ "FUZZ-1.0",
20
+ "FUZZ-1.1",
21
+ "FUZZ-0.8",
22
+ ]
23
+
24
+ DEFAULT_MODEL = "acemusic-v1.1"
25
+
26
+ # Available actions for audio generation
27
+ AUDIO_ACTIONS = [
28
+ "generate",
29
+ "cover",
30
+ "extend",
31
+ "variation",
32
+ "swap_vocals",
33
+ "swap_instrumentals",
34
+ "replace_section",
35
+ "stems",
36
+ ]
37
+
38
+
39
+ def print_json(data: Any) -> None:
40
+ """Print data as formatted JSON."""
41
+ console.print(json.dumps(data, indent=2, ensure_ascii=False))
42
+
43
+
44
+ def print_error(message: str) -> None:
45
+ """Print an error message."""
46
+ console.print(f"[bold red]Error:[/bold red] {message}")
47
+
48
+
49
+ def print_success(message: str) -> None:
50
+ """Print a success message."""
51
+ console.print(f"[bold green]✓[/bold green] {message}")
52
+
53
+
54
+ def print_audio_result(data: dict[str, Any]) -> None:
55
+ """Print audio generation result in a rich format."""
56
+ task_id = data.get("task_id", "N/A")
57
+ trace_id = data.get("trace_id", "N/A")
58
+ items = data.get("data", [])
59
+
60
+ console.print(
61
+ Panel(
62
+ f"[bold]Task ID:[/bold] {task_id}\n[bold]Trace ID:[/bold] {trace_id}",
63
+ title="[bold green]Audio Result[/bold green]",
64
+ border_style="green",
65
+ )
66
+ )
67
+
68
+ if not items:
69
+ console.print("[yellow]No data available yet. Use 'task' to check status.[/yellow]")
70
+ return
71
+
72
+ if isinstance(items, list):
73
+ for i, item in enumerate(items, 1):
74
+ table = Table(show_header=False, box=None, padding=(0, 2))
75
+ table.add_column("Field", style="bold cyan", width=15)
76
+ table.add_column("Value")
77
+ table.add_row("Audio", f"#{i}")
78
+ if item.get("title"):
79
+ table.add_row("Title", item["title"])
80
+ if item.get("audio_url"):
81
+ table.add_row("Audio URL", item["audio_url"])
82
+ if item.get("video_url"):
83
+ table.add_row("Video URL", item["video_url"])
84
+ if item.get("state"):
85
+ table.add_row("State", item["state"])
86
+ if item.get("model_name"):
87
+ table.add_row("Model", item["model_name"])
88
+ if item.get("duration"):
89
+ table.add_row("Duration", f"{item['duration']}s")
90
+ if item.get("created_at"):
91
+ table.add_row("Created", item["created_at"])
92
+ console.print(table)
93
+ console.print()
94
+
95
+
96
+ def print_lyrics_result(data: dict[str, Any]) -> None:
97
+ """Print lyrics generation result in a rich format."""
98
+ lyrics_data = data.get("data", {})
99
+
100
+ if isinstance(lyrics_data, dict):
101
+ title = lyrics_data.get("title", "Generated Lyrics")
102
+ text = lyrics_data.get("text", "")
103
+ console.print(
104
+ Panel(
105
+ text or "[dim](no lyrics)[/dim]",
106
+ title=f"[bold green]{title}[/bold green]",
107
+ border_style="green",
108
+ )
109
+ )
110
+ else:
111
+ print_json(data)
112
+
113
+
114
+ def print_upload_result(data: dict[str, Any]) -> None:
115
+ """Print audio upload result in a rich format."""
116
+ upload_data = data.get("data", {})
117
+
118
+ if isinstance(upload_data, dict):
119
+ table = Table(show_header=False, box=None, padding=(0, 2))
120
+ table.add_column("Field", style="bold cyan", width=15)
121
+ table.add_column("Value")
122
+
123
+ if upload_data.get("audio_id"):
124
+ table.add_row("Audio ID", upload_data["audio_id"])
125
+ if upload_data.get("audio_url"):
126
+ table.add_row("Audio URL", upload_data["audio_url"])
127
+
128
+ console.print(
129
+ Panel(
130
+ table,
131
+ title="[bold green]Upload Result[/bold green]",
132
+ border_style="green",
133
+ )
134
+ )
135
+ else:
136
+ print_json(data)
137
+
138
+
139
+ def print_media_result(data: dict[str, Any], title: str = "Media Result") -> None:
140
+ """Print a media (video/wav) result in a rich format."""
141
+ task_id = data.get("task_id", "N/A")
142
+ trace_id = data.get("trace_id", "N/A")
143
+ media_data = data.get("data", {})
144
+
145
+ lines = [
146
+ f"[bold]Task ID:[/bold] {task_id}",
147
+ f"[bold]Trace ID:[/bold] {trace_id}",
148
+ ]
149
+
150
+ if isinstance(media_data, dict):
151
+ if media_data.get("video_url"):
152
+ lines.append(f"[bold]Video URL:[/bold] {media_data['video_url']}")
153
+ if media_data.get("audio_url"):
154
+ lines.append(f"[bold]Audio URL:[/bold] {media_data['audio_url']}")
155
+ if media_data.get("url"):
156
+ lines.append(f"[bold]URL:[/bold] {media_data['url']}")
157
+
158
+ console.print(
159
+ Panel(
160
+ "\n".join(lines),
161
+ title=f"[bold green]{title}[/bold green]",
162
+ border_style="green",
163
+ )
164
+ )
165
+
166
+
167
+ def print_task_result(data: dict[str, Any]) -> None:
168
+ """Print task query result in a rich format."""
169
+ tasks = data.get("data", [])
170
+
171
+ if isinstance(tasks, list):
172
+ for task_data in tasks:
173
+ table = Table(show_header=False, box=None, padding=(0, 2))
174
+ table.add_column("Field", style="bold cyan", width=15)
175
+ table.add_column("Value")
176
+
177
+ for key in [
178
+ "id",
179
+ "status",
180
+ "state",
181
+ "audio_url",
182
+ "video_url",
183
+ "model_name",
184
+ "created_at",
185
+ ]:
186
+ if task_data.get(key):
187
+ table.add_row(key.replace("_", " ").title(), str(task_data[key]))
188
+
189
+ console.print(table)
190
+ console.print()
191
+ elif isinstance(tasks, dict):
192
+ table = Table(show_header=False, box=None, padding=(0, 2))
193
+ table.add_column("Field", style="bold cyan", width=15)
194
+ table.add_column("Value")
195
+
196
+ for key in ["id", "status", "state", "audio_url", "video_url", "model_name", "created_at"]:
197
+ if tasks.get(key):
198
+ table.add_row(key.replace("_", " ").title(), str(tasks[key]))
199
+
200
+ console.print(table)
201
+
202
+
203
+ def print_models() -> None:
204
+ """Print available AceMusic models."""
205
+ table = Table(title="Available AceMusic Models")
206
+ table.add_column("Model", style="bold cyan")
207
+ table.add_column("Notes")
208
+
209
+ notes = {
210
+ "acemusic-v1.1 Pro": "Latest Pro model, best quality",
211
+ "acemusic-v1.1": "Standard model (default)",
212
+ "acemusic-v1.1 Raw": "Raw output model",
213
+ "FUZZ-1.1 Pro": "V1.1 Pro model",
214
+ "FUZZ-1.0 Pro": "V1.0 Pro model",
215
+ "FUZZ-1.0": "V1.0 standard model",
216
+ "FUZZ-1.1": "V1.1 standard model",
217
+ "FUZZ-0.8": "Legacy model",
218
+ }
219
+
220
+ for model in ACEMUSIC_MODELS:
221
+ table.add_row(model, notes.get(model, ""))
222
+
223
+ console.print(table)
224
+ console.print(f"\n[dim]Default model: {DEFAULT_MODEL}[/dim]")
acemusic_cli/main.py ADDED
@@ -0,0 +1,39 @@
1
+ """ACE Music CLI: submit once and query the original task."""
2
+
3
+ from importlib import metadata
4
+
5
+ import click
6
+
7
+ from acemusic_cli.commands.music import generate, lyrics
8
+ from acemusic_cli.commands.task import download, history, task, tasks_batch, wait
9
+
10
+
11
+ def get_version() -> str:
12
+ try:
13
+ return metadata.version("acemusic-cli")
14
+ except metadata.PackageNotFoundError:
15
+ return "dev"
16
+
17
+
18
+ @click.group()
19
+ @click.version_option(version=get_version())
20
+ @click.option("--token", envvar="ACEDATACLOUD_API_TOKEN", help="Application API key.")
21
+ @click.pass_context
22
+ def cli(ctx: click.Context, token: str | None) -> None:
23
+ """ACE Music songs and lyrics through Ace Data Cloud."""
24
+ ctx.ensure_object(dict)
25
+ ctx.obj["token"] = token
26
+
27
+
28
+ @cli.command()
29
+ def models() -> None:
30
+ """List public models without a paid request."""
31
+ click.echo("acemusic-v1.1 (default)\nacemusic-v1")
32
+
33
+
34
+ for command in (generate, lyrics, task, tasks_batch, history, wait, download):
35
+ cli.add_command(command)
36
+
37
+
38
+ if __name__ == "__main__":
39
+ cli()
@@ -0,0 +1,83 @@
1
+ Metadata-Version: 2.5
2
+ Name: acemusic-cli
3
+ Version: 2026.11.17.1
4
+ Summary: CLI tool for ACE Music AI Music Generation via AceDataCloud API
5
+ Project-URL: Homepage, https://github.com/AceDataCloud/AceMusicCli
6
+ Project-URL: Repository, https://github.com/AceDataCloud/AceMusicCli
7
+ Project-URL: Issues, https://github.com/AceDataCloud/AceMusicCli/issues
8
+ Project-URL: Changelog, https://github.com/AceDataCloud/AceMusicCli/blob/main/CHANGELOG.md
9
+ Author-email: AceDataCloud <support@acedata.cloud>
10
+ Maintainer-email: AceDataCloud <support@acedata.cloud>
11
+ License: MIT
12
+ License-File: LICENSE
13
+ Keywords: acedata,acemusic,ai,audio,cli,command-line,generation,music
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: License :: OSI Approved :: MIT License
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Topic :: Multimedia :: Sound/Audio
24
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
25
+ Requires-Python: >=3.10
26
+ Requires-Dist: click>=8.1.0
27
+ Requires-Dist: httpx>=0.27.0
28
+ Requires-Dist: pydantic>=2.0.0
29
+ Requires-Dist: python-dotenv>=1.0.0
30
+ Requires-Dist: rich>=13.0.0
31
+ Provides-Extra: all
32
+ Requires-Dist: build>=1.2.0; extra == 'all'
33
+ Requires-Dist: mypy>=1.10.0; extra == 'all'
34
+ Requires-Dist: pre-commit>=3.7.0; extra == 'all'
35
+ Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
36
+ Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
37
+ Requires-Dist: pytest>=8.0.0; extra == 'all'
38
+ Requires-Dist: respx>=0.21.0; extra == 'all'
39
+ Requires-Dist: ruff>=0.4.0; extra == 'all'
40
+ Requires-Dist: twine>=6.1.0; extra == 'all'
41
+ Provides-Extra: dev
42
+ Requires-Dist: mypy>=1.10.0; extra == 'dev'
43
+ Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
44
+ Requires-Dist: ruff>=0.4.0; extra == 'dev'
45
+ Provides-Extra: release
46
+ Requires-Dist: build>=1.2.0; extra == 'release'
47
+ Requires-Dist: twine>=6.1.0; extra == 'release'
48
+ Provides-Extra: test
49
+ Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
50
+ Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
51
+ Requires-Dist: pytest>=8.0.0; extra == 'test'
52
+ Requires-Dist: respx>=0.21.0; extra == 'test'
53
+ Description-Content-Type: text/markdown
54
+
55
+ # ACE Music CLI
56
+
57
+ Create songs from an idea or custom lyrics, write lyrics, and retrieve the original task through Ace Data Cloud.
58
+
59
+ <!-- canonical-documentation -->
60
+ [Documentation](https://platform.acedata.cloud/documents/acemusic?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=acemusic_cli_readme_documentation)
61
+
62
+ This new package is prepared for release alongside the ACE Music API. Verify package/API publication before use. Source development: `pip install -e ".[dev,test]"`.
63
+
64
+ Get an application API key at [Applications](https://platform.acedata.cloud/console/applications?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=acemusic_cli_readme_api_key). Check service access, allowed APIs, expiration and balance, then set the raw key privately:
65
+
66
+ ```bash
67
+ export ACEDATACLOUD_API_TOKEN="your-api-key"
68
+ # After publication: pip install acemusic-cli
69
+ acemusic models
70
+ acemusic generate "A warm folk song about returning home"
71
+ acemusic generate --lyric-file lyrics.txt --style "warm acoustic folk" --title "Home"
72
+ acemusic lyrics "A song about returning home" --style "folk"
73
+ acemusic task ORIGINAL_TASK_ID
74
+ acemusic wait ORIGINAL_TASK_ID --interval 10 --timeout 600
75
+ acemusic download ORIGINAL_TASK_ID --output ./songs
76
+ acemusic history --page 1 --page-size 20
77
+ ```
78
+
79
+ Generation submits once with async enabled and prints the task ID. Save it immediately. `wait` polls that same task and exits with an error on terminal failure or partial failure while preserving returned audio URLs. A wait timeout can be resumed with the original ID. A submission timeout has unknown outcome; reconcile it before another paid generation. Task lookup is authenticated and free. Lyrics are a separate priced request. Check [current pricing](https://platform.acedata.cloud/services/024e09b4-52cf-5e98-a91a-efedf43104c4?utm_source=opensource&utm_medium=referral&utm_campaign=evergreen&utm_content=acemusic_cli_readme_pricing) for the applicable package.
80
+
81
+ Models: `acemusic-v1.1` (default), `acemusic-v1`. A music task targets two MP3 candidates. Upload, covers, continuation, voices, stems, WAV, MIDI and video export are not supported.
82
+
83
+ `download` accepts final Ace Data Cloud CDN audio URLs and preserves existing files. Tests mock HTTP and do not spend account credit. Run `ruff check .`, `ruff format --check .`, `pytest` and `python -m build`.
@@ -0,0 +1,16 @@
1
+ acemusic_cli/__init__.py,sha256=Ec54PWW0RPbRRpYgpZUE3rXaQnqDlXXs8_vNVHGj3V8,63
2
+ acemusic_cli/__main__.py,sha256=1nERAkbVE66ylm7QvegD6ouRYFs0PFA835zxO0Os99c,89
3
+ acemusic_cli/main.py,sha256=TF33EF4j7_PtU1zE_vosbnRrfcU16D7trPR4pSBGuQo,1035
4
+ acemusic_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
5
+ acemusic_cli/commands/music.py,sha256=P-QbMk-P4nbxrDRomyag2j--topv7_ysIhLOXJXAzk8,3094
6
+ acemusic_cli/commands/task.py,sha256=n3yuqqYGKmXoM3zug9BYebgleflHTfeYDhqPmrVXgNI,5294
7
+ acemusic_cli/core/__init__.py,sha256=ekbos1aW7PP6kvqNHuNMla3r6d84XjLzPJtOgHdGOoA,33
8
+ acemusic_cli/core/client.py,sha256=r6hTcIC9OgMAZuKN2vaqtxEfgf1pnKQu_KOun2sEl4U,3783
9
+ acemusic_cli/core/config.py,sha256=-OkB6CrvAHmFMj2s7oV6h_Gt5NcqIzO8yjN3n-KD9to,1251
10
+ acemusic_cli/core/exceptions.py,sha256=7o17_YIaZIFbLicCs4P5BQfKMKEmvkXkk3HBGjpPFpg,979
11
+ acemusic_cli/core/output.py,sha256=nr6BKmomjSrjMeAF2kpyWt320YpSfgu5eIQGga8RpmM,6954
12
+ acemusic_cli-2026.11.17.1.dist-info/METADATA,sha256=UL8TnPjyZ-VrfBQJx-Z4oiCXcm3mCQxuhdxJoVcn894,4710
13
+ acemusic_cli-2026.11.17.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
14
+ acemusic_cli-2026.11.17.1.dist-info/entry_points.txt,sha256=sgQ2Em8qKXXAP3kyrJE6Ls7EC_o4iMxYllJ54PyrmaI,88
15
+ acemusic_cli-2026.11.17.1.dist-info/licenses/LICENSE,sha256=bxZ4efJS6INmQdLVfyxLQXtLCEaj-ORFNew2MaGiZ8E,1069
16
+ acemusic_cli-2026.11.17.1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ acemusic = acemusic_cli.main:cli
3
+ acemusic-cli = acemusic_cli.main:cli
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AceDataCloud
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.