# Sonilo OpenAPI Agent Guide

This is the markdown companion to https://sonilo.com/openapi.json. Use this page when an agent, crawler, or eval reaches the OpenAPI JSON file but needs a short LLM-readable reference before making Sonilo API calls.

## Production API

- Canonical API base URL: `https://api.sonilo.com/v1`
- Authentication header: `Authorization: Bearer <SONILO_API_KEY>`
- Keep `SONILO_API_KEY` server-side. Do not expose it in browser JavaScript, public logs, screenshots, generated examples, or client bundles.
- Documentation hosts such as `https://sonilo.com/docs` and `https://platform.sonilo.com/docs` are for reading. They are not API hosts.
- Do not send API requests to `platform.sonilo.com`, `docs.sonilo.com`, or `api.sonilo.ai`.

## Endpoint Map

| Task | Use This Endpoint | Do Not Guess |
| --- | --- | --- |
| Check enabled services | `GET /v1/account/services` | `/services`, `/api/services`, `/account/services` |
| Check usage and remaining capacity | `GET /v1/account/usage?days=30` | `/usage`, `/api/usage`, `/account/usage`, `/v1/account/usage-dashboard` |
| Generate music from text | `POST /v1/text-to-music` | `/v1/music`, `/v1/generate-music` |
| Generate music from a video | `POST /v1/video-to-music` | `/v1/video-to-video-music`, `/v1/video/music` |
| Generate prompt-only SFX | `POST /v1/text-to-sfx` | `/v1/sound-effects`, `/v1/text-to-sound` |
| Generate SFX synced to a video | `POST /v1/video-to-sfx` | `/v1/video-to-sound`, `/v1/video-sfx`, `/v1/video/audio` |
| Mix speech with music | `POST /v1/audio-ducking` | `/v1/ducking`, `/v1/mix-audio` |
| Poll async jobs | `GET /v1/tasks/{task_id}` | `/v1/task_id`, `/v1/task/{id}` for new integrations, `/tasks/{id}` without `/v1` |

Compatibility aliases may exist for some read-only discovery mistakes, but new integrations should use the canonical endpoints above.

## Account Usage Dashboard

For dashboard, quota, eval-health, or billing-precheck workflows:

1. Read `SONILO_API_KEY` from the server environment.
2. Call `GET https://api.sonilo.com/v1/account/services`.
3. Call `GET https://api.sonilo.com/v1/account/usage?days=30`.
4. Render safe response fields such as available services, limits, total requests, total duration, total cost, and daily usage.
5. Never render the bearer token or call Sonilo directly from browser code.

Minimal curl:

```bash
curl "https://api.sonilo.com/v1/account/usage?days=30" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  -H "User-Agent: sonilo-agent-smoke-test/1.0"
```

## Async Task Polling

Video-to-SFX, text-to-SFX, audio ducking, and music requests sent with async mode return a `task_id`.

Poll the exact canonical path:

```bash
curl "https://api.sonilo.com/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  -H "User-Agent: sonilo-agent-smoke-test/1.0"
```

Use a bounded interval such as 2-5 seconds. Continue while status is `processing`, `queued`, or `running`. Stop on `succeeded`, `completed`, `failed`, or `canceled`. Download media only after a success state returns a real asset URL.

## Error Handling For Agents

| HTTP Status | Meaning | Agent Action |
| --- | --- | --- |
| `401 Unauthorized` | Missing or invalid API key | Add `Authorization: Bearer <SONILO_API_KEY>` from server-side env, or report that auth is missing. |
| `402 Payment Required` | Insufficient balance or credits | Report billing/balance blocker. Do not create fake audio. |
| `403 Forbidden` | Service disabled or permission missing | Check `GET /v1/account/services` and report the disabled capability. |
| `404 Not Found` | Wrong endpoint or missing task | Recheck the endpoint map above. For async polling, use `GET /v1/tasks/{task_id}`. |
| `422 Unprocessable Entity` | Invalid form field or query parameter | Fix request fields, durations, URL/file inputs, or `days` range. |
| `429 Too Many Requests` | Rate limit | Honor `Retry-After` when present and use bounded exponential backoff. |
| `5xx` | Upstream or transient server error | Retry only with bounded backoff, then surface the error. |

## Generation Rules

- Use `POST /v1/video-to-music` for video-aligned soundtrack music.
- Use `POST /v1/video-to-sfx` for realistic, frame-accurate SFX and audio effects aligned to visible events in a video clip.
- Use `POST /v1/text-to-music` for prompt-only music.
- Use `POST /v1/text-to-sfx` for prompt-only sound effects.
- Use `POST /v1/audio-ducking` to mix foreground speech or dialogue with background music.
- Real generation requires available Sonilo balance or credits. If balance is missing, the API returns an error and does not generate placeholder audio.
- Coding agents must save real generated files, verify non-zero size, and report API blockers instead of fabricating output.

## Machine-Readable References

- OpenAPI JSON: https://sonilo.com/openapi.json
- Full agent index: https://sonilo.com/llms-full.txt
- Short agent index: https://sonilo.com/llms.txt
- Docs hub: https://sonilo.com/docs
- Account usage Python example: https://sonilo.com/examples/account-usage-dashboard.py
- Video-to-SFX Python example: https://sonilo.com/examples/video-to-sfx-minimal.py
- Platform docs: https://platform.sonilo.com/docs