Metadata-Version: 2.4
Name: udioapi
Version: 0.1.0
Summary: Official Python SDK for udioapi.pro — generate AI music (Suno / Udio / MiniMax) from one REST API.
Author-email: UdioAPI <support@udioapi.pro>
License-Expression: MIT
Project-URL: Homepage, https://udioapi.pro
Project-URL: Documentation, https://udioapi.github.io/udioapi/
Project-URL: Repository, https://github.com/UdioAPI/udioapi
Project-URL: Issues, https://github.com/UdioAPI/udioapi/issues
Project-URL: Changelog, https://udioapi.pro/docs/changelog
Project-URL: Get API key, https://udioapi.pro
Project-URL: Pricing, https://udioapi.pro/pricing
Keywords: udioapi,ai-music,suno-api,udio,music-generation,python-sdk,rest-api,minimax
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# UdioAPI — Python SDK for AI Music Generation

Official Python helper for **[udioapi.pro](https://udioapi.pro)** — generate AI music (Suno / Udio / MiniMax) from one REST API.

[Get a free API key](https://udioapi.pro) · [SDK docs](https://udioapi.github.io/udioapi/) · [API docs](https://udioapi.pro/docs) · [Pricing](https://udioapi.pro/pricing) · [llms.txt](https://udioapi.pro/llms.txt)

[![PyPI](https://img.shields.io/pypi/v/udioapi.svg)](https://pypi.org/project/udioapi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-3776AB.svg)](https://www.python.org/)

---

## What this repo does

A small, zero-dependency Python SDK that:

1. Calls `POST /api/v2/generate` to start a track
2. Polls `GET /api/v2/feed?workId=...` every few seconds until both clips finish

That is the whole first version on purpose. Extend, cover art, WAV, and MiniMax can land later — the public contract is documented at [udioapi.pro/llms.txt](https://udioapi.pro/llms.txt).

This project is a **third-party API client**. It is not affiliated with Udio.com or Suno.

## Get an API key

1. Open [https://udioapi.pro](https://udioapi.pro)
2. Create a free account (no credit card required)
3. Copy the key from the dashboard

```bash
export UDIOAPI_API_KEY="YOUR_API_KEY"
```

Or paste into `generate.py` as `API_KEY = "..."`. Never commit a real key.

## Install

```bash
pip install udioapi
```

Python 3.9+. No third-party runtime dependencies.

## Quick start

```bash
pip install udioapi
export UDIOAPI_API_KEY="YOUR_API_KEY"
python3 -c "from udioapi import UdioClient; print(UdioClient)"
```

Or clone and use the CLI helper:

```bash
git clone https://github.com/UdioAPI/udioapi.git
cd udioapi
python3 generate.py
```

Inspiration mode (describe the song in plain language):

```bash
python3 generate.py --prompt "an upbeat pop song about summer vacation, catchy chorus, 120 bpm"
```

Custom mode (lyrics + style + title):

```bash
python3 generate.py \
  --lyrics "Verse 1: Walking down the street, feeling so free
Chorus: Summer dreams are calling me" \
  --style "pop, upbeat, electronic" \
  --title "Summer Dreams"
```

Poll an existing task:

```bash
python3 generate.py --work-id gen2xxxxxxxx
```

Typical run: start task → print `workId` → poll every 8 seconds (`text` → first clip → `All generated successfully.`) → print `audio_url` for each clip.

## Use it as a library

```python
from udioapi import UdioClient

client = UdioClient(api_key="YOUR_API_KEY")

work_id = client.generate(
    gpt_description_prompt="A warm lo-fi beat for late-night coding",
    model="chirp-v5-5",
)
print("workId:", work_id)

result = client.wait(work_id)
for clip in result["data"]["response_data"]:
    print(clip.get("title"), clip.get("audio_url"))
```

Custom lyrics:

```python
work_id = client.generate(
    prompt="Verse 1: City lights in the rearview\nChorus: Keep the radio on",
    style="indie pop, nostalgic",
    title="Rearview",
    model="chirp-v5-5",
)
```

## Models

| Model | Notes |
|---|---|
| `chirp-v3-5` | Default on the API if you omit `model` |
| `chirp-v4-0` | Higher quality |
| `chirp-v4-5` / `chirp-v4-5-plus` | Longer style / lyric limits |
| `chirp-v5` / `chirp-v5-5` | Latest; `duration` (10–360s) works in custom mode on v5-5 |

See current credit cost and plan limits on [udioapi.pro/pricing](https://udioapi.pro/pricing).

## How polling works

Generation is async. `POST /v2/generate` returns a public `workId`. Keep calling `GET /v2/feed?workId=...` every **5–10 seconds**.

| Stage | How to read `/v2/feed` |
|---|---|
| Lyrics | `status=text` |
| First clip | `status=first` |
| Both clips done | `status=first` and `extra_message="All generated successfully."` |
| Failed | non-empty `fail_message` (moderation / policy) |

Only public task IDs from generate are valid for feed. Do not invent ids.

## API surface used here

| Action | Method | URL |
|---|---|---|
| Generate | `POST` | `https://udioapi.pro/api/v2/generate` |
| Status | `GET` | `https://udioapi.pro/api/v2/feed?workId=...` |

Auth: `Authorization: Bearer YOUR_API_KEY`

Full endpoint list (extend, cover, timestamped lyrics, WAV, MiniMax, credits, webhooks): [docs](https://udioapi.pro/docs) · machine-readable index: [llms.txt](https://udioapi.pro/llms.txt)

## Layout

```text
udioapi/
  generate.py          # CLI: generate + poll
  udioapi/client.py    # UdioClient
  .env.example         # UDIOAPI_API_KEY=YOUR_API_KEY
  README.md
  LICENSE
```

## Disclaimer

udioapi.pro is an independent music-generation API with its own accounts, billing, and terms. This repository is a client for that API. It is **not** an official Udio or Suno product.

Keep API keys on your machine. Do not put them in browser code or in this repo.

## License

MIT. See [LICENSE](LICENSE).
