---
updatedAt: 2025-11-27T15:25:48.000Z
agentTools:
  projectIndex: https://docs.audiostack.ai/llms.txt
---

# Generate your first audio

```python Python SDK
import json
import os
import typing

import audiostack
import requests

audiostack.api_key = "YOUR API KEY"

audioform_str = """
{
    "header": {
      "version": "2"
    },
    "assets": {
      "script 0": {
        "type": "tts",
        "text": "Welcome to Audiostack! Generate your first audioform in seconds, with a great sounding voice and a sound template that fits perfectly.",
        "voiceRef": "main voice",
        "anchor": "1"
      },
      "main voice": {
        "type": "voice",
        "voiceAlias": "roxanne"
      },
      "sound template 0": {
        "type": "soundTemplate",
        "soundTemplateAlias":"daytime_song",
        "segment": "main"
      }
    },
    "production": {
      "arrangement": {
        "sections": [
          {
            "layers": [
              {
                "clips": [
                  {
                    "assetRef": "script 0"
                  }
                ]
              }
            ],
            "soundTemplateRef": "sound template 0",
            "smartFit": true,
            "paddingStart": 0.5,
            "paddingEnd": 1.5
          }
        ]
      },
      "masteringPreset": "balanced"
    },
    "delivery": {
      "loudnessPreset": "radio",
      "encoderPreset": "mp3",
      "public": false
    }
}
"""

# In production code you should check for exceptions and make sure the voice is found
print("Building audioform...")
audioform_json = json.loads(audioform_str)
audioform = audiostack.audioform.Audioform.create(audioform=audioform_json)
if audioform.is_in_progress or audioform.is_success:
    audioform = audioform.get(version="2", wait=True, timeoutThreshold=60)
    if audioform.is_success:
        url = audioform.result["delivery"]["uri"]
        name = f"audioform.{audioform.result["delivery"]["encoderPreset"]}"
        print("Audioform built successfully.")
        print(f"Downloading audioform as '{name}'...")
        audiostack.helpers.request_interface.RequestInterface.download_url(
            url=url,
            name=name,
            destination="./",
        )
        print("Downloaded Audioform successfully.")

```

```shell Shell
#!/bin/sh

# API configuration
API_KEY = "YOUR API KEY"
API_BASE="https://v2.api.audio"

# Step 1: Create audioform
echo "Creating audioform..."
AUDIOFORM_JSON=$(cat <<EOF
{
  "audioform": {
    "header": {
      "version": "2"
    },
    "assets": {
      "script 0": {
        "type": "tts",
        "text": "Welcome to Audiostack! Generate your first audioform in seconds, with a great sounding voice and a sound template that fits perfectly.",
        "voiceRef": "main voice",
        "anchor": "1"
      },
      "main voice": {
        "type": "voice",
        "voiceAlias": "roxanne"
      },
      "sound template 0": {
        "type": "soundTemplate",
        "soundTemplateAlias": "daytime_song",
        "segment": "main"
      }
    },
    "production": {
      "arrangement": {
        "sections": [
          {
            "layers": [
              {
                "clips": [
                  {
                    "assetRef": "script 0"
                  }
                ]
              }
            ],
            "soundTemplateRef": "sound template 0",
            "smartFit": true,
            "paddingStart": 0.5,
            "paddingEnd": 1.5
          }
        ]
      },
      "masteringPreset": "balanced"
    },
    "delivery": {
      "loudnessPreset": "radio",
      "encoderPreset": "mp3",
      "public": false
    }
  }
}
EOF
)

# Step 2: Submit the audioform

AUDIOFORM_CREATE_RESPONSE=$(curl -s -X POST \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${AUDIOFORM_JSON}" \
  "${API_BASE}/audioforms")

AUDIOFORM_ID=$(echo "${AUDIOFORM_CREATE_RESPONSE}" | jq -r '.data.audioformId // .audioformId')

# Step 3: Poll audioform status until complete
echo "Building audioform..."
TIMEOUT=60
ELAPSED=0
STATUS_CODE=202

while [ "${STATUS_CODE}" -eq 202 ]; do
  if [ "${ELAPSED}" -ge "${TIMEOUT}" ]; then
    echo "Timeout waiting for audioform to complete"
    exit 1
  fi
  
  echo "Audioform build in progress, please wait..."
  
  # Get status - curl outputs body then status code on separate lines
  AUDIOFORM_STATUS_RESPONSE=$(curl -s -w "\nHTTPSTATUS:%{http_code}" -X GET \
    -H "x-api-key: ${API_KEY}" \
    -H "version: 2" \
    "${API_BASE}/audioforms/${AUDIOFORM_ID}")
  
  STATUS_CODE=$(echo "${AUDIOFORM_STATUS_RESPONSE}" | grep -o "HTTPSTATUS:[0-9]*" | cut -d: -f2)
  # Default to 202 if status code extraction fails
  if [ -z "${STATUS_CODE}" ]; then
    STATUS_CODE=202
  fi
  AUDIOFORM_STATUS_BODY=$(echo "${AUDIOFORM_STATUS_RESPONSE}" | sed '/HTTPSTATUS:/d')
  
  if [ "${STATUS_CODE}" -eq 202 ]; then
    sleep 0.5
    ELAPSED=$((ELAPSED + 1))
  fi
done

# Step 4: Download the audioform
if [ "${STATUS_CODE}" -eq 200 ]; then
  DOWNLOAD_URL=$(echo "${AUDIOFORM_STATUS_BODY}" | jq -r '.data.result.delivery.uri // .result.delivery.uri')
  ENCODER_PRESET=$(echo "${AUDIOFORM_STATUS_BODY}" | jq -r '.data.result.delivery.encoderPreset // .result.delivery.encoderPreset')
  FILENAME="audioform.${ENCODER_PRESET}"

  echo "Audioform built successfully."
  echo "Downloading audioform as '${FILENAME}'..."
  
  curl --location "${DOWNLOAD_URL}" \
    --header "x-api-key: ${API_KEY}" \
    -o "./${FILENAME}" > /dev/null 2>&1
    
  echo "Downloaded Audioform successfully."
fi

```

```json Response Example
Building audioform...
Audioform build in progress, please wait...
(...)
Audioform built successfully.
Downloading audioform as 'audioform.mp3'...
Downloaded Audioform successfully.

```

# Setup the SDK

<!-- python@1-8 -->
<!-- shell@4-5 -->

Import the SDK and provide your developer API key.  
If using the SDK make sure the SDK in installed via pip.  The SDK must be version at version 4 or higher to support audioform.

# Define the audioform

<!-- python@10-60 -->
<!-- shell@9-62 -->

This audioform uses the voice "roxanne" and the sound template "daytime_song".  
The music starts 0.5 before the begining of the voice and continues for 1.5 after the end.  
The sound template uses the smart fit feature, which allow a great ending of the music, whatever is the duration of the audio.  
The audio adapts to the duration of the speech. 

# Build the audioform

<!-- python@62-68 -->
<!-- shell@66-105 -->

Submit the audioform, then poll the the endpoint until we have a successful build result, which contains all the information we need to retrieve the audio.

# Download the audio file

<!-- python@69-78 -->
<!-- shell@108-121 -->

Retrieve the result url and download the file at that url