# Scenario Audio Studio — API Reference Model ID: `model_scenario-audio-studio` --- ## Authentication - **API_KEY** and **API_SECRET** are found in your [Scenario Project Settings](https://app.scenario.com/team&tab=api_keys) under API Keys. - Set them as environment variables `SCENARIO_SDK_API_KEY` and `SCENARIO_SDK_API_SECRET` — both SDKs pick them up by default. - For raw HTTP (cURL), use Basic Auth: `Authorization: Basic base64(":")`. ### Install the SDK - JavaScript / TypeScript: `npm install @scenario-labs/sdk` - Python: `pip install scenario-sdk` --- ## Generate **Endpoint:** `POST https://api.cloud.scenario.com/v1/generate/custom/model_scenario-audio-studio` ### Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `prompt` | string | - | - | What to make: style, mood, instruments, tempo, key and structure, like "warm lo-fi hip-hop at 80 BPM with a dusty piano", or the sound effect, like "a retro coin pickup". Optional when you add an image, an audio, a video, samples or Strudel code. | | `audioType` | string | - | `music` | Music, or sound effects. Without a duration, music lasts 30 s and sound effects 3 s. | | `image` | assetId | - | - | Optional. An image to score: the music follows its mood and setting. | | `audio` | assetId | - | - | Optional. A recording to accompany, match or rebuild: the result follows its tempo and key, starting on its first beat. Not with a video. | | `video` | assetId | - | - | Optional. A video to score: hits land on its cuts, and it comes back with the new soundtrack. Not with a reference audio. | | `samples` | assetId[] | - | - | Optional. Up to 8 of your own sounds for the result to play: one-shots (a drum hit, a single note), loops or phrases. The program plays them as sample1, sample2 and so on, in this order: a note is tuned and becomes melodies and chords, a loop plays at its own tempo, and loops and phrases can be chopped. Each keeps its first 60 s. | | `transcribeAudio` | boolean | - | `false` | With a reference audio: split it into stems, transcribe their notes and play them on new instruments in the style of the prompt. Needs Rights Confirmed. | | `rightsConfirmed` | boolean | - | `false` | Confirms that the music rebuilt from the reference audio is yours to use, or in the public domain. Required by Rebuild From Notes. | | `mixWithInput` | boolean | - | `false` | Keep the reference audio, or the video's own sound, under the result. | | `returnVideo` | boolean | - | `true` | With a video: also return it with the new soundtrack. | | `duration` | number | - | - | Seconds, up to 180. Leave empty to match the video or the reference audio (up to 180 s), else 30 s of music or 3 s of sound effects. Longer results cost more. | | `thinkingLevel` | string | - | `high` | How much Claude thinks before each draft. Higher levels write richer arrangements and cost more. | | `maxIterations` | number | - | `5` | How many times Claude may render, listen to and revise the piece, the final render included. More drafts polish the result and cost more. | | `code` | string | - | - | Optional. A Strudel program, like the code a previous run returned: rendered as is without a prompt or media, revised by Claude with them. | | `outputFormat` | string | - | `mp3` | Format of the delivered audio. | ### Example Requests **cURL** ```bash curl -X POST "https://api.cloud.scenario.com/v1/generate/custom/model_scenario-audio-studio" \ -H "Authorization: Basic $(echo -n ':' | base64)" \ -H "Content-Type: application/json" \ --data-binary @- <<'EOF' { "audioType": "music", "transcribeAudio": false, "rightsConfirmed": false, "mixWithInput": false, "returnVideo": true, "thinkingLevel": "high", "maxIterations": 5, "outputFormat": "mp3" } EOF ``` **Python** ```python import os from scenario_sdk import Scenario client = Scenario( api_key=os.environ.get("SCENARIO_SDK_API_KEY"), api_secret=os.environ.get("SCENARIO_SDK_API_SECRET"), ) body = { "audioType": "music", "transcribeAudio": False, "rightsConfirmed": False, "mixWithInput": False, "returnVideo": True, "thinkingLevel": "high", "maxIterations": 5, "outputFormat": "mp3" } response = client.generate.run_model( model_id="model_scenario-audio-studio", body=body, ) print(response) ``` **JavaScript** ```javascript import Scenario from "@scenario-labs/sdk"; const client = new Scenario({ apiKey: process.env["SCENARIO_SDK_API_KEY"], apiSecret: process.env["SCENARIO_SDK_API_SECRET"], }); const body = { "audioType": "music", "transcribeAudio": false, "rightsConfirmed": false, "mixWithInput": false, "returnVideo": true, "thinkingLevel": "high", "maxIterations": 5, "outputFormat": "mp3" }; const response = await client.generate.runModel("model_scenario-audio-studio", { body }); console.info(response); ``` --- ## Retrieve Results After submitting a generation request, you receive a `jobId`. Poll the job until `job.status` is `"success"`. The generated asset IDs are in `job.metadata.assetIds`. **Endpoint:** `GET https://api.cloud.scenario.com/v1/jobs/{jobId}` ### Example Requests **cURL** ```bash curl -X GET "https://api.cloud.scenario.com/v1/jobs/" \ -H "Authorization: Basic $(echo -n ':' | base64)" ``` **Python** ```python job = client.jobs.retrieve(job_id="") print(job.status) print(job.metadata.asset_ids) ``` **JavaScript** ```javascript // Option 1 — wait on the response from runModel using the SDK helper const completed = await response.job.wait(); console.info(completed.status); console.info(completed.metadata?.assetIds); // Option 2 — retrieve a job by its ID const job = await client.jobs.retrieve(""); console.info(job.status); console.info(job.metadata?.assetIds); ``` **Example response:** ```json { "job": { "jobId": "job_abc123", "status": "success", "metadata": { "assetIds": [ "asset_abc123" ] } } } ``` > **Important:** Generated asset URLs are **temporary** and expire after a short period. Download and store any images you wish to keep before the URL expires. More info: [Content Delivery Network (CDN)](https://docs.scenario.com/get-started/documentation/content-delivery-network-cdn). --- *Generated by [Scenario](https://app.scenario.com)*