Mureka music and speech

VideoClaw connects to Mureka through useapi.net for songs, instrumental music, narration and dialogue. It uses the existing soundtrack selection and audio artifacts, so generated audio can be previewed and used in a film.

Connect your account

1. Complete useapi's Mureka setup. You need both a useapi subscription and a Mureka account. Signing up alone does not link them: use the setup page's Add account form. The provider supports email/password or session-token linking.

2. Save your complete useapi token in your workspace .env.local, not in the package or a tracked source file. Existing USEAPI_API_TOKEN values work across useapi services if the subscription permits Mureka access.

   USEAPI_API_TOKEN=your-complete-useapi-token
   # Optional when one Mureka account is linked; required when several exist:
   VCLAW_MUREKA_ACCOUNT=your-mureka-account-id
   # Optional; omission uses the provider's account default:
   VCLAW_MUREKA_MODEL=V9.5
   # Optional default for speech, from the voice lookup below:
   VCLAW_MUREKA_VOICE_ID=your-numeric-voice-id

3. Verify without spending credits:

   vclaw video mureka --root /path/to/workspace
   vclaw video mureka --voices --root /path/to/workspace

The account check omits credentials. A token's presence only makes the backend locally available; it does not prove the linked account or paid plan is ready. For HTTP 401/403 check the complete token and useapi subscription. For account errors, reconnect through the setup page. Do not paste passwords into prompts.

Generate music

With an existing project, preview an instrumental request first:

vclaw video soundtrack --project my-film --root /path/to/workspace --backends mureka --prompt "Warm cinematic strings and soft piano" --instrumental --dry-run

For a live generation, replace --dry-run with --confirm-spend after approving the generation spend. Explicitly use --backends mureka to select only Mureka; omitting the flag runs every available music backend.

• With --instrumental, the prompt limit is 1,000 characters.
• With --lyrics "[Verse] ...", the lyrics limit is 5,000 characters and the musical description (--prompt) limit is 1,000 characters.
• With neither flag, Mureka generates a vocal song from the prompt (up to 3,000 characters).
• Combining lyrics and instrumental is rejected before submission.
• Supported model settings: V9.5, V9, V8, O2, V7.6, V7.5. Availability depends on the Mureka plan.
• --duration is a dry-run estimate. The provider chooses the live song length; VideoClaw records its actual duration rather than promising an exact length.

The first returned song is saved as artifacts/audio/soundtrack-mureka.mp3. Both returned songs' IDs and URLs are retained in the adjacent .mureka.json receipt. Select the soundtrack for the project without regenerating:

vclaw video soundtrack --project my-film --root /path/to/workspace --select mureka

Narration and dialogue

Use a numeric ID returned by video mureka --voices, or configure VCLAW_MUREKA_VOICE_ID. Voice names such as “Sarah” are not IDs.

vclaw video narrate --project my-film --root /path/to/workspace --backend mureka-tts --voice 12345 --text "Our story begins here." --dry-run
vclaw video dialogue --project my-film --root /path/to/workspace --backend mureka-tts --voice 12345 --turns "Alex: Hello. || Sam: Welcome." --dry-run

Replace the example voice ID with a real one. Speech is limited to 5,000 characters per generation. Dialogue creates one clip per turn; library callers can supply a different voice for each turn. Outputs are MP3. Live generation requires --confirm-spend.

Recover a generation

The receipt <audio-path>.mureka.json is saved immediately after submission. If polling or downloading fails, inspect the recorded job instead of generating again:

vclaw video mureka --job 'the-recorded-job-id' --root /path/to/workspace

Completed job results contain download URLs. useapi retains job records for seven days. A network failure during submission can leave the outcome unknown; check the provider's job history before resubmitting. VideoClaw never retries a paid submission automatically. Polling defaults to 120 checks at three-second intervals, configurable with VCLAW_MUREKA_POLL_MAX_ATTEMPTS and VCLAW_MUREKA_POLL_INTERVAL_MS. Downloads never receive the useapi token.

This integration exposes music and speech. Mureka's API does not document a dedicated sound-effects endpoint; VideoClaw's existing sfx backend remains available. Stem extraction, song editing, reference uploads and voice cloning are separate Mureka features not exposed by these commands.

Source: Mureka API v1.

Download a generated song's stems

vclaw video mureka --stems <song_id> --out <zip-path> [--account <id>]

Downloads the existing Mureka song's stem ZIP through useapi; it does not generate a song. The linked account needs stem-download entitlement. The original song ID is required; this endpoint does not separate arbitrary uploaded tracks.

The command saves the archive and a .mureka.json sidecar containing the provider, song ID, SHA-256, byte count and download timestamp. A matching archive is reused without another request. Existing mismatched or incomplete outputs are refused; choose a new output path. Downloads check the ZIP signature but do not extract or validate individual stems. A separate extraction and audio verification step is still required before using these files for rendering. CDN requests do not carry the API token, and failed submissions are not automatically retried.