sonilo

Official Python client for the Sonilo API. Python ≥ 3.9. Sync and async clients included.

Installation

pip install sonilo

Quickstart

from sonilo import Sonilo

client = Sonilo()  # reads SONILO_API_KEY

track = client.text_to_music.generate(
    prompt="cinematic orchestral score",
    duration=60,
)
track.save("output.mp3")
print(track.title)

Video to music

track = client.video_to_music.generate(video="my_video.mp4", prompt="upbeat")
# or bytes / an open binary file, or a hosted URL:
track = client.video_to_music.generate(video_url="https://example.com/clip.mp4")

Vocal isolation (async)

Pass isolate_vocals=True to also get an isolated vocal stem and a muxed video, alongside the scored audio. This requires async processing — submit returns a task_id immediately, and generate_async() wraps submit + poll:

result = client.video_to_music.generate_async(
    video="my_video.mp4",
    prompt="upbeat",
    isolate_vocals=True,  # implies mode="async"; omit mode to let it auto-select
)
result.save("mix.m4a")           # result.audio[0] — the full mix
result.save("vocals.m4a", which="vocals")
result.save("video.mp4", which="mux")  # video muxed with the generated audio
print(result.title.title if result.title else None)

Or control submission and polling yourself:

from sonilo.resources.tasks import parse_music_result

task = client.video_to_music.submit(video_url="https://example.com/clip.mp4", isolate_vocals=True)
result = client.tasks.wait(
    task.task_id,
    parser=parse_music_result,  # required: tasks.wait()/get() default to the SFX parser
)

isolate_vocals=True with an explicit non-async mode raises SoniloError locally before any request is sent.

Streaming

for event in client.text_to_music.stream(prompt="lofi", duration=30):
    if event["type"] == "audio_chunk":
        handle(event["data"])  # bytes, as they arrive

Async

from sonilo import AsyncSonilo

async with AsyncSonilo() as client:
    track = await client.text_to_music.generate(prompt="lofi", duration=30)
    async for event in client.text_to_music.stream(prompt="lofi", duration=30):
        ...

Segments

Shape the composition with start-only contiguous segments (each ends where the next begins):

client.text_to_music.generate(
    prompt="epic trailer",
    duration=60,
    segments=[
        {"start": 0, "prompt": "soft intro", "label": "intro"},
        {"start": 20, "prompt": "building tension", "label": "verse"},
        {"start": 40, "prompt": "full orchestra", "label": "chorus"},
    ],
)

Sound effects (async tasks)

SFX endpoints are asynchronous: submitting returns a task_id, and the result is fetched by polling. generate() wraps submit + poll:

from sonilo import Sonilo

with Sonilo() as client:
    result = client.text_to_sfx.generate(prompt="glass shattering", duration=5)
    result.save("sfx.m4a")

Or control polling yourself:

task = client.video_to_sfx.submit(
    video="clip.mp4",
    segments=[{"start": 0, "end": 2.5, "prompt": "footsteps on gravel"}],
    audio_format="wav",
)
result = client.tasks.wait(task.task_id, poll_interval=2.0, timeout=600.0)
result.save("audio.wav")  # video-to-sfx returns the generated audio only

tasks.get(task_id) fetches state once and never raises on a failed task; tasks.wait() / generate() raise TaskFailedError (with .code, .refunded) on failure and TaskTimeoutError if the deadline passes — the task keeps running server-side and can still be polled afterwards. Result URLs are presigned and expire; download promptly or re-fetch via tasks.get.

Account

client.account.services()
client.account.usage(days=7)

Errors

All errors extend SoniloError: AuthenticationError (401), PaymentRequiredError (402), RateLimitError (429, .retry_after), BadRequestError (400/413/422, .detail), APIError (anything else), GenerationError for failures mid-stream, TaskFailedError (.code, .task_id, .refunded) for a failed SFX task, and TaskTimeoutError (.task_id) when tasks.wait() / generate() hits its deadline.

Every APIError also carries .status_code, .body (the parsed response), .code (the API's error code, e.g. "rate_limit_exceeded"), and .errors (the validation detail list on a 422), in addition to any subclass-specific attributes above.