Skip to content

Latest commit

 

History

History
261 lines (205 loc) · 6.25 KB

README.md

File metadata and controls

261 lines (205 loc) · 6.25 KB

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
  1. 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"
  1. 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.