# Sonilo quickstart for coding agents

Canonical docs: https://platform.sonilo.com/docs/quickstart
Source path: /docs/quickstart
Runtime API host: https://api.sonilo.com/v1

Use this for the simplest Sonilo text-to-music workflow in Codex, Claude, Sapient, and other coding-agent evals.

## Prerequisites

- Install the official Python SDK with `pip install sonilo`.
- Set `SONILO_API_KEY` in the environment.
- Real generation requires available API credits / balance.
- If Sonilo returns 402 payment_required or insufficient_balance, do not create placeholder audio. Report the balance state.

## 30-second instrumental text-to-music example

```python
import os
from pathlib import Path

from sonilo import Sonilo, SoniloError

output = Path("output.mp3")
client = Sonilo(api_key=os.environ["SONILO_API_KEY"])

try:
    track = client.text_to_music.generate(
        prompt="30 seconds of upbeat electronic instrumental background music for a product launch video, no vocals",
        duration=30,
    )
    track.save(output)
    print(f"Saved {output} ({output.stat().st_size} bytes)")
except SoniloError as exc:
    message = str(exc)
    if "insufficient_balance" in message or "payment_required" in message:
        raise SystemExit("Sonilo account needs credits before real audio can be generated") from exc
    raise
```

## Raw API fallback

- Endpoint: POST https://api.sonilo.com/v1/text-to-music
- Auth: Authorization: Bearer <SONILO_API_KEY>
- Required fields: prompt, duration
- Stream mode returns NDJSON audio_chunk events followed by complete; write real audio bytes to output.m4a.
- Raw runnable example: https://platform.sonilo.com/examples/text-to-music-output.py