feat: text-to-sfx, video-to-sfx and task polling (v0.2.0)

[spencer-zqian]

Adds the three new SFX endpoints to the Python SDK, and fixes a set of bugs found along the way — several of which affect the already-shipped music endpoints too.

What's new

SFX is submit-then-poll (unlike the streaming music endpoints), so the SDK wraps the polling but keeps the primitives exposed:

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

task = client.video_to_sfx.submit(
    video="clip.mp4",                       # or video_url=...
    segments=[{"start": 0, "end": 2.5, "prompt": "footsteps on gravel"}],
    audio_format="wav",
)
result = client.tasks.wait(task.task_id)    # or tasks.get() for a single poll
result.save("audio.wav")
result.save("with_audio.mp4", which="video")

• text_to_sfx / video_to_sfx: submit() (returns SfxTask) and generate() (= submit + wait).
• tasks: get() (single fetch, never raises on a failed task) and wait() (polls to a terminal state).
• SfxResult.save() / asave() download the presigned R2 URLs; no API key is ever sent to the R2 host.
• New errors: TaskFailedError (with .code, .refunded) and TaskTimeoutError (resumable — the task keeps running server-side).
• AsyncSonilo mirrors the whole surface.

Bug fixes (several pre-date this branch)

The SDK was parsing an error field the API never sends. The public /v1/* routes return {"code", "message"} (see backend/app/errors.py), not FastAPI's {"detail"} — so every API error degraded to HTTP 400: Bad Request and the real cause was discarded. This affected the shipped music endpoints too. APIError now exposes .code and .errors (422 validation details), and BadRequestError.detail works again.

Also fixed, all with regression tests:

• Silent audio corruption: base64.b64decode() is lenient by default — it discards invalid characters and re-aligns, so a corrupted audio_chunk decoded to wrong, shorter bytes and generate() returned a "successful" Track with silently truncated audio. Now decodes strictly, matching the JS SDK's atob() semantics (WHATWG forgiving-base64) on all 21 payloads cross-checked.
• A malformed audio_chunk (missing data) was silently dropped as an unknown event, likewise yielding empty audio with no error. Now raises GenerationError.
• A bare null NDJSON line crashed with an untyped AttributeError.
• Malformed task bodies raised a bare KeyError, bypassing callers' except SoniloError.
• SfxResult.save()/asave() used httpx's 5-second default timeout — any real download with a >5s stall failed. Now 600s, overridable.
• tasks.get() didn't URL-encode the task id.
• wait() slept the full poll interval past its own deadline, and sync/async disagreed on a negative poll_interval (one raised, the other busy-polled). Both now validate and clamp.

Verification

pytest: 126 passing.

End-to-end against production: text-to-sfx and video-to-sfx (multipart upload + segments) both generate, poll, download and save real audio/video — downloaded bytes match the reported file_size, WAV/MP3/MP4 headers validate, and the muxed video carries the generated audio track. Error mapping, validation, 404s and path-injection guards verified live.

Versions bumped 0.1.0 → 0.2.0. The mirrored JS SDK change is sonilo-ai/sonilo-js#1.