Udio API Wrapper

A Python wrapper for the udioapi.pro API that makes it easy to generate AI music based on text prompts.

Getting Started

Prerequisites

• Python 3.7 or higher
• pip (Python package installer)
• An API key from udioapi.pro

Getting an API Key

1. Visit udioapi.pro
2. Create an account or log in
3. Navigate to your dashboard
4. Generate a new API key
5. Copy and save your API key securely - you'll need it to use the wrapper

Installation

1. Clone this repository:

git clone https://github.com/yourusername/UdioApiWrapper.git
cd UdioApiWrapper

Note: If you downloaded the code directly instead of cloning, just navigate to the UdioApiWrapper directory:

cd path/to/UdioApiWrapper

2. Install the package in development mode:

pip install -e .

Quick Start

1. Set your API token as an environment variable:

export UDIO_API_TOKEN="your-api-token"

2. Run the test script to verify everything works:

python test_api.py

Basic Usage

from udio_api_wrapper import UdioApiClient

# Initialize the client
client = UdioApiClient(token="your-api-token")

# Generate a simple song
result = client.generate_music(
    prompt="A relaxing piano melody with soft strings",
    title="Peaceful Morning",
    model="chirp-v3.5"
)

# Get the work ID from the result
work_id = result['workId']
print(f"Generation started with work ID: {work_id}")

# Wait for the generation to complete and get the results
final_result = client.wait_for_completion(work_id)

# Print the generated track URLs
for track in final_result.get('response_data', []):
    print(f"\nTitle: {track.get('title')}")
    print(f"Audio URL: {track.get('audio_url')}")
    print(f"Tags: {track.get('tags')}")

Advanced Usage

Generating Music with Lyrics

# Generate a song with specific lyrics
result = client.generate_music(
    prompt="""[Verse]
Your lyrics here
[Chorus]
More lyrics here""",
    title="My Song",
    model="chirp-v3.5",
    make_instrumental=False  # Set to False to include vocals
)

Using Custom Mode

# Generate using custom mode
result = client.generate_music(
    prompt="Epic orchestral soundtrack",
    title="Epic Theme",
    style="orchestral",
    custom_mode=True,
    model="chirp-v3.5"
)

Using Callback URLs

# Generate with callback URL
result = client.generate_music(
    prompt="Jazz improvisation",
    title="Jazz Session",
    model="chirp-v3.5",
    callback_url="https://your-server.com/webhook"
)

API Reference

Available Models

Model	Description	Best For
chirp-v3.5	Latest version	Best quality, recommended for most uses
chirp-v3.0	Previous version	Stable, well-tested
udio-130	Long-form model	2:10 minute clips
udio-32	Short-form model	32-second clips

Generation Parameters

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the desired music
title	string	No	Title for the generated track
gpt_description_prompt	string	No	Additional context for GPT
custom_mode	boolean	No	Enable custom generation mode
make_instrumental	boolean	No	Generate without vocals
model	string	No	Model to use (default: "chirp-v3.0")
callback_url	string	No	Webhook URL for results
cluster	string	No	Server cluster (default: "default")

Custom Mode Requirements

customMode	instrumental	Required Parameters
true	false	style, prompt, title
true	true	style, title
false	true	prompt
false	false	prompt

Error Handling

The wrapper includes comprehensive error handling:

try:
    result = client.generate_music(prompt="Your prompt")
except UdioApiError as e:
    print(f"API Error: {str(e)}")
except Exception as e:
    print(f"Unexpected error: {str(e)}")

Common error scenarios:

• Authentication errors (invalid API token)
• Invalid parameters
• Network issues
• Generation failures
• Rate limiting

Best Practices

1. API Token Security

   • Never commit your API token to version control
   • Use environment variables or secure configuration management
   • Rotate tokens periodically

2. Prompt Engineering

   • Keep prompts clear and concise
   • Include specific musical elements you want
   • Avoid overly long prompts that may cause errors

3. Resource Management

   • Generated files are stored for 30 days
   • Monitor your API usage
   • Use appropriate models for your needs

4. Performance Optimization

   • Use the backup cluster during high traffic
   • Implement proper error handling
   • Cache results when possible

Example Responses

Successful Generation Request

{
    "message": "success",
    "workId": "your-work-id"
}

Callback Response

{
    "code": 200,
    "data": {
        "callbackType": "complete",
        "data": [
            {
                "audio_url": "https://xxx.mp3",
                "createTime": 1717587606036,
                "duration": 146.08,
                "id": "59001af3-845d-47af-9e23-625adb0c6505",
                "image_url": "https://xxx.png",
                "model_name": "chirp-v3.5",
                "prompt": "your prompt",
                "tags": "melodic pop piano",
                "title": "your title"
            }
        ]
    },
    "msg": "All generated successfully."
}

Troubleshooting

Common Issues and Solutions

1. Authentication Errors

   • Verify your API token is correct
   • Check if the token has expired
   • Ensure the token is properly set in the environment

2. Generation Failures

   • Check if the prompt is too long
   • Verify all required parameters are provided
   • Ensure you're using a valid model name

3. Network Issues

   • Check your internet connection
   • Verify the API endpoint is accessible
   • Consider using a different cluster

4. Rate Limiting

   • Monitor your API usage
   • Implement exponential backoff
   • Contact support if you need higher limits

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.