beatra-ai-music-creator

AI Music Creator

Develop a theme, scene, lyric fragment, complete lyric, functional music brief, or reference recording into one coherent musical direction and, when the user wants audio, one intentional generation request. The deliverable may be a song, instrumental, BGM, soundtrack, jingle, multilingual track, or reference-led new arrangement. Treat singer identity, pronunciation, exact duration, loop points, melody carryover, and mastering as qualities to review after generation rather than guaranteed properties.

Use the bundled scripts/mcp_client.py for every Beatra operation. Do not configure or use a host Beatra Connector. Never use REST/OpenAPI as a fallback. For ordinary calls, run python3 scripts/mcp_client.py call and pass one JSON object on stdin. For local files, use only the dedicated upload command described below. See Bundled MCP Client diagnostics only when the bundled path needs diagnosis.

Shape the direction first

Reuse every settled choice in the conversation. Infer ordinary creative details from the destination when that is safe. Ask only when a missing answer changes the lyrics, reference direction, vocal or instrumental route, exact paid payload, or another high-impact user choice.

Before generation, prepare one compact production card:

• destination and listener;
• title, premise, emotional arc, primary genre, tempo feel, instrumentation, structure, mix direction, ending or loop direction, and exclusions;
• vocal or instrumental route;
• full lyrics, language and register, and vocal direction when the track has vocals;
• selected model and model-specific controls;
• reference intent and the qualities that should carry over or change when a reference is involved; and
• the fact that the next action is one billable generation.

For instrumentals, omit lyrics and make room for dialogue or other functional needs in the creative direction. For vocal music, finish and show material lyric changes before generation. Lyrics writing, creative planning, model discovery, prompt preparation, and critique do not require a paid music call. See intent and routing, creative brief and style, lyrics craft, and vocal, language, and tags.

When a brief uses artist shorthand, translate it into actionable genre, era, tempo, instrumentation, harmony, vocal texture, phrasing, and mix attributes.

Choose and validate the model

Set model: "suno-5.5" for this package's ordinary generation. Never omit the model and never silently use auto. Call beatra.models.list with capability text_to_music or reference_audio_to_music when the user requests another model, asks about current availability or price, or needs a model-specific capability. Do not silently substitute a model.

Use only controls returned or documented for the selected model family. Suno and MiniMax options are not interchangeable. Validate the exact payload using model routing and use the examples in music recipes as patterns rather than fixed claims.

Use reference audio

For a local FLAC, MP3, or WAV reference, run only:

python3 scripts/mcp_client.py upload  --mime-type 

The bundled command obtains and validates the upload grant, uploads exactly the file bytes, and returns the artifact to use as reference_audio. Do not replace it with host HTTP, a connector, REST, or a hand-written grant and PUT sequence. The general upload limit is 100 MB; the selected music model can impose a lower size or duration limit.

Describe what should carry over and what should change. A reference guides a new creative result; after generation, review melody, vocal character, energy, instrumentation, and arrangement against that direction.

Confirm the paid boundary once

A direct, well-specified request to generate authorizes that exact request once. Approval of the complete production card also authorizes it once. Do not add a second confirmation. An estimate, comparison, lyric review, direction choice, or “do not generate yet” is not approval.

Before a billable call, make model, title, lyrics or instrumental status, reference, important controls, and the one-generation scope visible. Create a stable 1..128-character client_request_id only after that payload is final. Any change to prompt, lyrics, instrumental flag, title, model, reference, model options, or any other argument accepted by the current or a future MCP generation schema is a new paid request with a new identity and confirmation. Fields outside the published MCP schema are ignored and do not change the request identity or task.

Let the bundled client perform its cached, best-effort, non-billable beatra.installations.register step automatically. Do not add manual registration to the creative workflow.

Submit beatra.music.generate once. Retain its task_id and poll the same task with beatra.tasks.get. Honor a returned deadline_at; otherwise stop active polling after 30 minutes, report the current state and how to resume, and do not resubmit. Cancel only when the user asks via beatra.tasks.cancel; if cancel conflicts with a terminal transition, return to the same task.

For an uncertain submission or lost task ID, search recent work with beatra.tasks.list using the matching music capability. List results do not contain the complete request: call beatra.tasks.get for each plausible candidate and compare its task.input, resolved model, reference, and options with the saved full payload. Only an exact identical retry may reuse the same client_request_id. Never create replacement paid work merely because a response was lost or a task is slow. See tasks and results and billing, errors, and recovery.

Deliver and review the music

On success, present every task.output.clips entry in returned order. Include the returned title and lyrics when present plus clip.audio.url, artifact ID, duration, MIME type, and size. Report factual task identity and billing.net_charged_credits. When the task returns task.links.assets, use that exact destination for asset management; do not invent a generic URL.

Review composition, lyrics, vocal performance, pronunciation, role assignment, arrangement, ending, and production only when the host can actually play the audio. Otherwise label listening review incomplete while still delivering the factual artifacts. Preserve successful qualities and turn the largest gap into one focused, newly approved generation. Follow review and iteration.

References by task

• Intent, lyrics, instrumental, multilingual, and reference routes: intent and routing
• Brief, style, lyrics craft, vocal direction, and language: creative brief and style, lyrics craft, and vocal, language, and tags
• Current model selection and exact payload controls: model routing
• Request patterns and focused result review: music recipes and review and iteration
• First installation or expired authorization: installation and authentication
• Bundled command syntax and diagnostics: Bundled MCP Client diagnostics
• Task recovery, billing, and returned results: tasks and results and billing, errors, and recovery
• Automatic update behavior and persistent controls: automatic updates and safety
• Package removal and shared credential handling: uninstall and disconnect

Automatic updates and removal

Before ordinary Beatra commands, the bundled client silently checks for a higher package version at most once every 24 hours. It uses the fixed official discovery address and immutable official CDN source. It may automatically install that higher version without separate confirmation. It verifies the archive, manifest, and every packaged file, and replaces only package-owned files. If checking, download, verification, replacement, or recovery fails, the current installation stays usable and the original command continues; an update failure never permits a paid retry.

The per-installation choice persists:

python3 scripts/mcp_client.py update --auto off
python3 scripts/mcp_client.py update --auto on
python3 scripts/mcp_client.py update --check

See automatic updates and safety for the complete verified-update contract. For removal or credential cleanup, follow uninstall and disconnect. Never directly delete ~/.beatra or shared credentials because another Beatra package may use the same connection.