# AI Music Generator (`visita/ai-music-generator`) Actor Transform your ideas into professional-grade, radio-ready tracks in seconds. This powerhouse Apify Actor connects to cutting-edge AI music models to give you a complete, automated music production studio right at your fingertips. This tool is designed for speed, creativity, and seamless automation. - **URL**: https://apify.com/visita/ai-music-generator.md - **Developed by:** [Visita Intelligence](https://apify.com/visita) (community) - **Categories:** AI, Social media, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $60.00 / 1,000 generated tracks This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## AI Music Studio & Generator Generate AI songs, remixes, instrumentals, lyric videos, cover art, and personas from one Apify Actor. This Actor is designed for creators, agencies, and product teams that need a reliable, automation-friendly music workflow. You can run it from the Apify Console UI or API, schedule jobs, monitor runs, and connect outputs to your own systems using webhooks. ### What does this AI Music Generator Actor do? This Actor turns a prompt or reference track into production-ready music assets. It supports **8 studio modes**, an **AI Co-Writer**, a **Premium Audio Vault**, and post-production workflows for **media, persona generation, and free details lookup**. Fastest way to try it: 1. Set `studioMode` to `original-creation`. 2. Enable `generateLyricsLLM`. 3. Choose `libraryGenre`, `songMood`, and run. ### What can this Actor do? - 🎚️ End-to-end music workflow: generate audio first, then visuals/persona with `taskId`. - 🤖 AI lyric writing with genre-aware structure and mood control. - 📚 Remix support from custom audio links or Premium Audio Vault tracks. - 🎬 Generate media assets from existing songs. - 🧑‍🎤 Generate and reuse AI personas with persistent persona profile storage. - 🧠 Optional persona-profile conditioning for LLM lyrics via `submitPersonaProfileToLLM`. - 🧩 Split stems and extend tracks for post-production. - 🔎 Free generation details retrieval by `taskId` or `audioId` with `get-details` mode. - ☁️ Built-in Apify advantages: scheduling, API access, webhooks, logs, dataset export, and run monitoring. ### Studio Modes Explained #### 1. `original-creation` Create a new song from scratch from your prompt or AI-generated lyrics. #### 2. `cover-remix` Generate a new vocal/lyrical interpretation over existing audio from: - `custom-link` - `premium-library` #### 3. `instrumental-magic` Add or reshape instrumental backing around source content. #### 4. `stem-splitter` Split tracks into isolated elements (for example, vocals and instrumentals). #### 5. `extend-track` Append new sections to an existing track for longer edits/versions. #### 6. `generate-media` Generate visual assets from an existing music `taskId`. #### 7. `generate-persona` Generate persona output from an existing music `taskId`. #### 8. `get-details` Fetch generation details by `taskId` or `audioId` without consuming generation credits. ### How to generate AI music with this Apify Actor 1. Choose `studioMode`. 2. If needed, select `audioSource` and provide `customAudioLink` or vault settings. 3. Enable `generateLyricsLLM` for automatic songwriting, or provide manual `prompt`. 4. Configure `libraryGenre`, `style`, and optional mood/theme settings. 5. Run the Actor and save returned `taskId`. 6. For visuals/persona, run again in `generate-media` or `generate-persona` mode using that `taskId`. 7. To reuse persona in future songs, enable `usePersona`, set `generationPersonaName`, and optionally enable `submitPersonaProfileToLLM`. ### How much does AI music generation cost on Apify? Pricing depends on your selected pricing model and consumed resources per run. - Cost can vary by mode, run duration, selected model, and polling behavior. - Audio-first + follow-up media/persona runs usually give clearer cost control than one complex run. - You can monitor usage in run logs and billing pages, then optimize by reducing retries and tightening input scope. Tip: for large pipelines, use `callBackUrl` + `asyncPassthrough` to avoid long blocking runs. ### Persona Workflow (Recommended) 1. Generate music (`original-creation` or `cover-remix`) and keep the returned `taskId`. 2. Run `generate-persona` with `personaTaskId`, `personaName`, and `personaDescription`. 3. The Actor stores the persona profile in its internal DB (Apify KV store) for later reuse. 4. For future generation runs, enable `usePersona` and set `generationPersonaName`. 5. Enable `submitPersonaProfileToLLM` only when you want persona description guidance included in lyric generation. Notes: - Persona lookup is case-insensitive. - If `submitPersonaProfileToLLM` is enabled and persona is not found, the run fails with `PERSONA_NOT_FOUND`. - If `usePersona` is enabled but no persona name is provided, the run fails with `PERSONA_NAME_REQUIRED`. ### Input Example Use the **Input** tab in Apify Console for full field descriptions. Example payload: ```json { "studioMode": "original-creation", "generateLyricsLLM": true, "llmModel": "openai/gpt-4o-mini", "libraryGenre": "amapiano", "songMood": "hype-euphoric", "songTheme": "party-hype", "prompt": "", "style": "female vocals, warm bass, club-ready", "model": "V4_5ALL", "pollingIntervalSeconds": 20, "asyncPassthrough": false } ```` ### Output Example You can export dataset items as JSON, CSV, XML, RSS, Excel, and more. ```json { "status": "SUCCESS", "taskId": "1234567890abcdef", "audioId": "53487c0d-1643-47c7-ad76-4859038ad645", "title": "Midnight Code", "style": "amapiano, female vocals, club", "audio_url": "https://.../track.mp3", "video_url": "https://.../lyric-video.mp4", "image_url": "https://.../cover.jpg", "persona_id": "2774abf480d5b38fc761820dfc7c9c4d", "persona_name": "Know Peace", "persona_description": "Short persona summary used for continuity", "persona_status": "PENDING", "persona_error": null } ``` ### What data does this Actor return? | Field | Description | |---|---| | `status` | Run outcome (`SUCCESS`, `FAILED`, etc.) | | `taskId` | Task identifier used for polling and follow-up modes | | `audioId` | Audio identifier used for media/persona follow-up modes | | `audio_url` | Generated audio track URL | | `video_url` | Generated video URL (when available) | | `image_url` | Generated cover/image URL (when available) | | `title` | Song title | | `style` | Final style tags used in generation | | `persona_id` | Generated persona identifier | | `persona_name` | Persona name used/generated | | `persona_description` | Persona description/profile summary | | `persona_status` | Persona workflow status | | `persona_error` | Persona error details (if any) | ### Why use this Actor on Apify instead of a raw script? - Reliable scheduling and retries. - Built-in run logs and observability. - API-first orchestration for apps and no-code tools. - Easy dataset export and downstream integrations. - One hosted workflow instead of multiple custom services. ### Other Actors by this creator If you use multiple automation workflows, consider building a connected stack of Actors for: - content generation - media processing - publishing automation Add your related Actor links here as you expand your Store portfolio. ### FAQ, Troubleshooting, and Support #### Why did I not get video or image in the same run? Use `generate-media` with an existing successful music `taskId`. Media generation is a follow-up workflow. #### Why did I get `PERSONA_NOT_FOUND`? The provided `generationPersonaName` does not exist in the Actor's persona profile DB for this Actor run history. First create it in `generate-persona` mode, then reuse it (case-insensitive name matching is supported). #### Why did I get `PERSONA_NAME_REQUIRED`? You enabled `usePersona` but did not provide `generationPersonaName`. #### What does `submitPersonaProfileToLLM` do? When enabled, a short saved persona description is sent to the lyric LLM for stylistic conditioning. When disabled, persona is still submitted to Suno generation payload (voice/style continuity) without profile text conditioning in LLM prompts. #### Why are my lyrics too short or too generic? - Enable `generateLyricsLLM`. - Provide clearer `songTheme` or `llmPrompt` context. - Add stronger `style` tags and choose an appropriate `libraryGenre`. #### What if a selected genre has no vault tracks? The Actor applies fallback behavior to keep generation working. Genre-aware lyric prompting still follows your selected genre instructions. #### Is this Actor beginner-friendly? Yes. You can run point-and-click from Input UI. Advanced users can automate with API, webhooks, and async orchestration. #### Is generated content legal to use? You are responsible for complying with applicable copyright, platform, and local laws for prompts, references, and outputs. Avoid infringing source material and consult legal counsel for commercial edge cases. #### Where can I get help? - Check run logs and dataset output first. - Review Input tab field descriptions. - Open an issue or contact the maintainer through the Actor page for support and feature requests. # Actor input Schema ## `studioMode` (type: `string`): Choose your generation pipeline (Create from scratch, Remix/Cover a track, Extract/Add Instrumentals, or Generate Media from Existing Song). ## `audioSource` (type: `string`): If remixing or using instrumental mode, choose where the audio comes from. ## `customAudioLink` (type: `string`): Direct URL to an MP3 or audio file (if Audio Source is 'Custom URL Link'). ## `libraryGenre` (type: `string`): Select the genre for your track. Each genre has unique LLM prompting for authentic sound. ## `libraryTrackName` (type: `string`): The exact track name to load from the catalog (e.g. 'synth\_pop\_anthem.mp3'). ## `taskId` (type: `string`): REQUIRED for media/persona generation modes. For other modes, if provided, skips generation and directly polls the status of this existing Task ID instead. Get this from a previous successful music generation run. ## `pollingIntervalSeconds` (type: `integer`): How often to check for the task completion status (in seconds). Recommended: 20-30 seconds for music generation. ## `callBackUrl` (type: `string`): URL to receive completion notifications directly from Suno API. ## `asyncPassthrough` (type: `boolean`): If enabled AND a Webhook Callback URL is provided, the Actor will exit instantly after starting the task, preventing long wait times. You MUST handle the webhook response on your end. ## `generateLyricsLLM` (type: `boolean`): If enabled, our LLM will dynamically write context-aware lyrics based on your Prompt and the selected Studio Mode/Backing Track! ## `llmModel` (type: `string`): Select the OpenRouter model to write the lyrics. Better models provide higher quality artistic expression. ## `songMood` (type: `string`): Determines the emotional tone and artistic style of the AI-generated lyrics, forcing it to sound human, raw, and expressive. ## `songTheme` (type: `string`): Select the main theme/topic for the song, or select 'Custom Theme' to type your own. ## `llmPrompt` (type: `string`): If 'Custom Theme' is selected above, type your specific instructions or topic here. ## `songLanguage` (type: `string`): Select the language you want the lyrics to be generated in. We also support 'Native + English Blend' which naturally mixes English with culturally appropriate native phrasing (e.g. Spanish + English for Reggaeton, Zulu + English for Amapiano). ## `customLanguage` (type: `string`): If 'custom' is selected above, type your preferred language here. ## `songAccent` (type: `string`): Select the specific regional slang or dialect for the lyrics. ## `customAccent` (type: `string`): If 'custom' is selected above, type your preferred accent or slang here. ## `prompt` (type: `string`): If Custom Mode is true: Limits: V4 (3000 chars), V4.5+ (5000 chars); Required if Instrumental is false. If Custom Mode is false: Limit: 500 chars. If 'Use AI Co-Writer' is enabled, the AI output overwrites this field safely. ## `model` (type: `string`): Model version to use. ## `customMode` (type: `boolean`): Enable custom parameter mode for advanced control. ## `stylePresets` (type: `array`): Select multiple presets to guide the musical style. We will dynamically insert these into the styling engine! ## `style` (type: `string`): Music style/genre (required in custom mode). Limits: V4 (200 chars), V4.5+ (1000 chars). Ignored if Custom Mode is false. ## `title` (type: `string`): Song title (required in custom mode). Limits: V4/V4.5ALL (80 chars), V4.5/V4.5PLUS/V5 (100 chars). Ignored if Custom Mode is false. ## `instrumental` (type: `boolean`): Generate instrumental-only music without vocals. ## `usePersona` (type: `boolean`): Enable to use a previously generated AI persona for consistent vocal style and characteristics. ## `generationPersonaName` (type: `string`): Name of the AI Persona to use for generation (must match a previously created persona). ## `submitPersonaProfileToLLM` (type: `boolean`): If enabled, the saved persona description is sent to the lyric LLM as style guidance. Disable to use persona voice only at Suno request level. ## `mediaTaskId` (type: `string`): REQUIRED for generate-media mode. Provide the Task ID from a previous successful music generation run to create video and cover art. ## `videoAuthor` (type: `string`): Optional author name for the music video (max 50 chars). ## `videoDomainName` (type: `string`): Optional domain name / watermark for the music video (max 50 chars). ## `stemAudioId` (type: `string`): The audio ID to separate (required if Studio Mode is Stem Splitter). ## `stemTaskId` (type: `string`): The task ID associated with the audio ID (required if Studio Mode is Stem Splitter). ## `personaTaskId` (type: `string`): REQUIRED for generate-persona mode. Provide the Task ID from a previous successful music generation run. The Actor will automatically fetch the audioId from this task. ## `personaName` (type: `string`): Name for the AI Persona (required for persona generation). ## `personaDescription` (type: `string`): Detailed description of the Persona's musical characteristics, style, and personality (required for persona generation). ## `extendAudioId` (type: `string`): The audio ID to extend (required if Studio Mode is Extend Track). ## `extendTime` (type: `string`): At what timestamp to extend the track. ## `detailsTaskId` (type: `string`): Provide a Task ID from a previous music generation run to fetch full generation details. ## `detailsAudioId` (type: `string`): Alternatively, provide an Audio ID (track ID) to fetch details. Either Task ID or Audio ID is required for this mode. ## Actor input object example ```json { "studioMode": "original-creation", "audioSource": "premium-library", "libraryGenre": "pop", "pollingIntervalSeconds": 20, "asyncPassthrough": false, "generateLyricsLLM": false, "llmModel": "openai/gpt-4o-mini", "songMood": "dynamic-match", "songTheme": "auto", "songLanguage": "American", "songAccent": "Chicago drill", "model": "V4_5ALL", "customMode": false, "instrumental": false, "usePersona": false, "submitPersonaProfileToLLM": false } ``` # Actor output Schema ## `overview` (type: `string`): No description ## `dataset` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("visita/ai-music-generator").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("visita/ai-music-generator").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call visita/ai-music-generator --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=visita/ai-music-generator", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "AI Music Generator", "description": "Transform your ideas into professional-grade, radio-ready tracks in seconds. This powerhouse Apify Actor connects to cutting-edge AI music models to give you a complete, automated music production studio right at your fingertips. This tool is designed for speed, creativity, and seamless automation.", "version": "0.0", "x-build-id": "XTUZhCwTveL2EtpvI" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/visita~ai-music-generator/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-visita-ai-music-generator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/visita~ai-music-generator/runs": { "post": { "operationId": "runs-sync-visita-ai-music-generator", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/visita~ai-music-generator/run-sync": { "post": { "operationId": "run-sync-visita-ai-music-generator", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "studioMode": { "title": "🎚️ Studio Mode", "enum": [ "original-creation", "cover-remix", "instrumental-magic", "stem-splitter", "extend-track", "generate-media", "generate-persona", "get-details" ], "type": "string", "description": "Choose your generation pipeline (Create from scratch, Remix/Cover a track, Extract/Add Instrumentals, or Generate Media from Existing Song).", "default": "original-creation" }, "audioSource": { "title": "🔊 Audio Source", "enum": [ "custom-link", "premium-library" ], "type": "string", "description": "If remixing or using instrumental mode, choose where the audio comes from.", "default": "premium-library" }, "customAudioLink": { "title": "🔗 Custom Audio Link", "type": "string", "description": "Direct URL to an MP3 or audio file (if Audio Source is 'Custom URL Link')." }, "libraryGenre": { "title": "🎵 Music Genre", "enum": [ "pop", "kids", "birthday", "christmas-new-year", "rap-hip-hop", "trap", "drill", "r&b", "soul", "gospel", "house", "afro-house", "amapiano", "deep-house", "slap-house", "bass-house", "tech-house", "electro-house", "edm", "trance", "progressive-house", "future-house", "acid-house", "french-house", "big-room-house", "chicago-house", "rock", "alt-rock", "indie-rock", "country", "blues", "jazz", "funk", "love-songs", "oldies", "latin", "reggaeton", "dancehall", "afrobeat", "afro-pop", "indie", "alternative", "lo-fi", "community-creations" ], "type": "string", "description": "Select the genre for your track. Each genre has unique LLM prompting for authentic sound.", "default": "pop" }, "libraryTrackName": { "title": "🎵 Library Track Name", "type": "string", "description": "The exact track name to load from the catalog (e.g. 'synth_pop_anthem.mp3')." }, "taskId": { "title": "🔑 Task ID", "type": "string", "description": "REQUIRED for media/persona generation modes. For other modes, if provided, skips generation and directly polls the status of this existing Task ID instead. Get this from a previous successful music generation run." }, "pollingIntervalSeconds": { "title": "⏱️ Polling Interval", "type": "integer", "description": "How often to check for the task completion status (in seconds). Recommended: 20-30 seconds for music generation.", "default": 20 }, "callBackUrl": { "title": "🔔 Webhook Callback URL", "type": "string", "description": "URL to receive completion notifications directly from Suno API." }, "asyncPassthrough": { "title": "⚡ Async Passthrough (Zero-Duration)", "type": "boolean", "description": "If enabled AND a Webhook Callback URL is provided, the Actor will exit instantly after starting the task, preventing long wait times. You MUST handle the webhook response on your end.", "default": false }, "generateLyricsLLM": { "title": "🤖 Use AI Co-Writer", "type": "boolean", "description": "If enabled, our LLM will dynamically write context-aware lyrics based on your Prompt and the selected Studio Mode/Backing Track!", "default": false }, "llmModel": { "title": "🧠 AI Producer Model", "enum": [ "openai/gpt-4o-mini", "openai/gpt-5.1", "google/gemini-3.1-pro", "anthropic/claude-3-opus" ], "type": "string", "description": "Select the OpenRouter model to write the lyrics. Better models provide higher quality artistic expression.", "default": "openai/gpt-4o-mini" }, "songMood": { "title": "🎭 Song Mood / Vibe", "enum": [ "dynamic-match", "raw-aggressive", "melancholy-heartbreak", "hype-euphoric", "chill-lofi", "sarcastic-playful" ], "type": "string", "description": "Determines the emotional tone and artistic style of the AI-generated lyrics, forcing it to sound human, raw, and expressive.", "default": "dynamic-match" }, "songTheme": { "title": "?? Song Theme", "enum": [ "auto", "love-romance", "success-grind", "heartbreak-betrayal", "party-hype", "rebellion-angst", "custom" ], "type": "string", "description": "Select the main theme/topic for the song, or select 'Custom Theme' to type your own.", "default": "auto" }, "llmPrompt": { "title": "?? Custom Theme / Prompt", "type": "string", "description": "If 'Custom Theme' is selected above, type your specific instructions or topic here." }, "songLanguage": { "title": "🌐 Language", "enum": [ "Native + English Blend", "English", "Spanish", "French", "German", "Italian", "Portuguese", "Japanese", "Korean", "Chinese", "Hindi", "Arabic", "Russian", "Swahili", "Zulu", "Yoruba", "custom" ], "type": "string", "description": "Select the language you want the lyrics to be generated in. We also support 'Native + English Blend' which naturally mixes English with culturally appropriate native phrasing (e.g. Spanish + English for Reggaeton, Zulu + English for Amapiano).", "default": "American" }, "customLanguage": { "title": "🌐 Custom Language", "type": "string", "description": "If 'custom' is selected above, type your preferred language here." }, "songAccent": { "title": "🗣️ Vocal Accent / Slang", "enum": [ "American", "British", "Chicago", "UK/London", "Jamaican Patois", "West African Pidgin", "South African", "auto", "custom" ], "type": "string", "description": "Select the specific regional slang or dialect for the lyrics.", "default": "Chicago drill" }, "customAccent": { "title": "🗣️ Custom Accent / Slang", "type": "string", "description": "If 'custom' is selected above, type your preferred accent or slang here." }, "prompt": { "title": "📝 Lyrics / Suno Prompt", "type": "string", "description": "If Custom Mode is true: Limits: V4 (3000 chars), V4.5+ (5000 chars); Required if Instrumental is false. If Custom Mode is false: Limit: 500 chars. If 'Use AI Co-Writer' is enabled, the AI output overwrites this field safely." }, "model": { "title": "🔧 Model", "enum": [ "V4", "V4_5", "V4_5PLUS", "V4_5ALL", "V5" ], "type": "string", "description": "Model version to use.", "default": "V4_5ALL" }, "customMode": { "title": "⚙️ Custom Mode", "type": "boolean", "description": "Enable custom parameter mode for advanced control.", "default": false }, "stylePresets": { "title": "🎨 Style Presets", "type": "array", "description": "Select multiple presets to guide the musical style. We will dynamically insert these into the styling engine!", "items": { "type": "string", "enum": [ "Male Vocals", "Female Vocals", "Heavy Bass", "Acoustic", "Electronic", "Fast Tempo", "Slow Tempo", "Synth", "Piano", "Acapella" ] } }, "style": { "title": "Style", "type": "string", "description": "Music style/genre (required in custom mode). Limits: V4 (200 chars), V4.5+ (1000 chars). Ignored if Custom Mode is false." }, "title": { "title": "Title", "type": "string", "description": "Song title (required in custom mode). Limits: V4/V4.5ALL (80 chars), V4.5/V4.5PLUS/V5 (100 chars). Ignored if Custom Mode is false." }, "instrumental": { "title": "🎹 Instrumental", "type": "boolean", "description": "Generate instrumental-only music without vocals.", "default": false }, "usePersona": { "title": "🎤 Use AI Persona", "type": "boolean", "description": "Enable to use a previously generated AI persona for consistent vocal style and characteristics.", "default": false }, "generationPersonaName": { "title": "👤 Persona Name", "type": "string", "description": "Name of the AI Persona to use for generation (must match a previously created persona)." }, "submitPersonaProfileToLLM": { "title": "🧠 Submit Persona Profile To LLM", "type": "boolean", "description": "If enabled, the saved persona description is sent to the lyric LLM as style guidance. Disable to use persona voice only at Suno request level.", "default": false }, "mediaTaskId": { "title": "🔑 Media Generation Task ID", "type": "string", "description": "REQUIRED for generate-media mode. Provide the Task ID from a previous successful music generation run to create video and cover art." }, "videoAuthor": { "title": "Video Author", "type": "string", "description": "Optional author name for the music video (max 50 chars)." }, "videoDomainName": { "title": "🌐 Video Domain Name", "type": "string", "description": "Optional domain name / watermark for the music video (max 50 chars)." }, "stemAudioId": { "title": "Stem Audio ID", "type": "string", "description": "The audio ID to separate (required if Studio Mode is Stem Splitter)." }, "stemTaskId": { "title": "Stem Task ID", "type": "string", "description": "The task ID associated with the audio ID (required if Studio Mode is Stem Splitter)." }, "personaTaskId": { "title": "🎤 Persona Task ID", "type": "string", "description": "REQUIRED for generate-persona mode. Provide the Task ID from a previous successful music generation run. The Actor will automatically fetch the audioId from this task." }, "personaName": { "title": "💫 Persona Name", "type": "string", "description": "Name for the AI Persona (required for persona generation)." }, "personaDescription": { "title": "📝 Persona Description", "type": "string", "description": "Detailed description of the Persona's musical characteristics, style, and personality (required for persona generation)." }, "extendAudioId": { "title": "Extend Audio ID", "type": "string", "description": "The audio ID to extend (required if Studio Mode is Extend Track)." }, "extendTime": { "title": "Extend Time (e.g. 02:30 or 150)", "type": "string", "description": "At what timestamp to extend the track." }, "detailsTaskId": { "title": "📋 Task ID", "type": "string", "description": "Provide a Task ID from a previous music generation run to fetch full generation details." }, "detailsAudioId": { "title": "🎵 Audio ID", "type": "string", "description": "Alternatively, provide an Audio ID (track ID) to fetch details. Either Task ID or Audio ID is required for this mode." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```