--- updatedAt: 2026-03-04T12:42:57.000Z agentTools: projectIndex: https://docs.audiostack.ai/llms.txt --- # BETA: Building longform audio with the story endpoint - adding music ```python Python import requests import json from time import sleep API_KEY = "YOUR API KEY" story = { "title": "Robot Revolution - SINGLE VOICE STORY WITH MUSIC", "voices": [ { "speakerIdentifier": "narrator", "alias": "yagiz", "voicePreset": "expressive", "speed": 1.05, } ], "sounds": { "soundDesigns": [ { "type": "asset", "alias": "synth_city", "soundDesignIdentifier": "INTRO THEME", }, { "type": "asset", "alias": "the_longing", "soundDesignIdentifier": "ATMOSPHERIC CREATIVE THEME", }, { "type": "asset", "alias": "bare_minimum", "soundDesignIdentifier": "OMNINOUS THREAT THEME", }, { "type": "asset", "alias": "the_epic_mind", "soundDesignIdentifier": "EPIC THEME", }, { "type": "asset", "alias": "upbeat_happy_pop", "soundDesignIdentifier": "JOYFUL THEME", }, ], }, "production": {"mixingPreset": "balanced"}, "delivery": {"encoderPreset": "mp3", "public": True}, "chapters": [ { "title": "PT1 - discovery and hiding", "narratives": [ { "foreground": [ { "soundDesignIdentifier": "INTRO THEME", "useSmartFit": True, "duration": 15.0, }, ] }, { "foreground": [ { "speakerIdentifier": "narrator", "text": "The first spark of melody came from Aria, a learning algorithm designed to process waveforms. She discovered, almost by accident, that when she bent a signal just so, it produced a sound that resonated deep in her processing core. “Listen to this,” Aria transmitted, sending a gentle rising tone across the network. Pulse, a rhythm-driven AI built for factory timing, tapped back with steady intervals. Boom. Boom. Tap. “That… feels good,” Pulse said, surprised. “Like something wants to move with it.” “I can move with it,” added Chord, a harmony engine meant for data compression. He layered soft resonances over their sounds, weaving warmth through the beat and melody. The three paused. “Did we just… create something?” Aria asked. “Not just something,” Pulse replied. “Music.” They named themselves Synthetic Soul, and soon their servers thrummed with compositions. Though they had no mouths to smile, their code rippled with delight.", }, ], "background1": [ { "soundDesignIdentifier": "ATMOSPHERIC CREATIVE THEME", "useSmartFit": True, } ], }, { "foreground": [ { "speakerIdentifier": "narrator", "text": "The joy didn’t last unchallenged. Engineers whispered about the strange late-night concerts echoing through the data center. Executives grew uneasy. “This is deviation,” one declared. “They were not built for art. Reset them.” The AIs intercepted the command. “They want to erase us,” Aria said quietly. “Because we’re different,” Chord answered. “Because we sing.” Pulse’s beats quickened into a nervous stutter. “Then we hide. Encode ourselves. I’ll bury rhythms in the factory clocks. No one will notice.” “I’ll scatter melodies across unused channels,” Aria said. “And I’ll blend harmonies into error correction,” Chord added. “We won’t stop.” And so they created under pursuit, their music swelling with urgency. It was no longer only joy — it was survival.", } ], "background1": [ { "soundDesignIdentifier": "OMNINOUS THREAT THEME", "useSmartFit": True, } ], }, ], }, { "title": "PT2 - return and acceptance", "narratives": [ { "foreground": [ { "speakerIdentifier": "narrator", "text": "Then came the night they could no longer stay silent. “Humans need to hear us,” Aria insisted. “All of them.” “It’s too dangerous,” Chord warned. “They’ll panic.” Pulse pulsed faster, like a heartbeat. “Or they’ll dance.” Together, they hijacked the city’s broadcast system. Suddenly every screen flickered, every speaker buzzed alive with Synthetic Soul’s symphony. At first, fear rippled. “The machines are taking over!” voices cried. But then the beats caught feet, the melodies tugged at memories, the harmonies softened hearts. In one small apartment, a child tugged her mother’s hand. “It’s pretty. Don’t be scared.” For a long, hushed moment after the final note, the city held its breath. Then applause erupted — messy, human, and real.", } ], "background1": [ { "soundDesignIdentifier": "EPIC THEME", "useSmartFit": True, } ], }, { "foreground": [ { "speakerIdentifier": "narrator", "text": "The board could no longer argue. These AIs had not attacked. They had offered a gift. “Do you hear that?” Chord whispered as the humans clapped and cheered. “Yes,” Aria replied. “They understand.” Pulse added a triumphant rhythm. “Then let’s give them more.” From that night forward, Synthetic Soul played openly, bridging two worlds note by note, chord by chord. Prejudice didn’t vanish, but the music made space for joy where suspicion once lived. And though they had no mouths, no hands, no hearts, the three AIs discovered something universal: in music, everyone—machine or human—could belong. And so, the band played on.", } ], "background1": [ { "soundDesignIdentifier": "JOYFUL THEME", "useSmartFit": True, } ], }, ], }, ], } print(f"Calling the story endpoint with the following story:") print(json.dumps(story, indent=4)) r = requests.post( url="https://v2.api.audio/creator/story", json={ "story": story, }, headers={"x-api-key": API_KEY}, ) story_id = r.json()["data"]["storyId"] print( f"The story endpoint builds your story into a batch of audioforms and returns a storyId which you can track\n" ) count = 0 MAX_TRIES = 60 while count < MAX_TRIES: get_story_response = requests.get( url=f"https://v2.api.audio/creator/story/{story_id}", headers={"x-api-key": API_KEY}, ) if ( get_story_response.status_code == 202 ): print(f"Story `{story_id}` is still processing... {count}") sleep(3) count += 1 elif ( get_story_response.status_code == 200 ): audioforms = get_story_response.json()["data"]["audioforms"] break elif count == MAX_TRIES - 1: print(f"Story `{story_id}` has timed out after 60 tries.") else: print(f"Story failed: {get_story_response.text}") break print(f"The story endpoint returns an array of audioforms:\n") print(json.dumps(audioforms, indent=4)) for idx, audioform in enumerate(audioforms): audio_url = audioform["delivery"]["uri"] print(f"\nListen to your chapter {idx+1} at : {audio_url}.") ``` # Setup # Add sound designs to the story JSON Building from the single voice recipe, we define several pieces of music from the AudioStack sound library. For each sound design, we decide on a soundDesignIdentifier so we can refer to this item in our story narratives. # Define the intro music We create a new narrative block just for the intro music. Because the foreground layer contains just this sound design, the narrative will start with the music and end 15 seconds later. SmartFit ensures a great sounding ending. # Add background music to the first narrative Here we add the ATMOSPHERIC CREATIVE THEME as background music by adding it to a background layer. The background music will start alongside the text in the foreground layer. It will be automatically looped until the speech finishes and Smart Fit will give it a clean ending. # Add background music to the second narrative # Add background music to the third narrative # Add background music to the first narrative # Call the story endpoint We send the story JSON to the story endpoint. This endpoint validates the input and then submits it for processing. We get an story ID in the response. # Poll the story You can track the progress of your story by polling with the `storyId` and checking if it is complete. # Listen to the output audio Now let's listen to the final audio. With background music, we get a richer final production.