# Text to Sound Effects API

Canonical docs: https://platform.sonilo.com/docs/api/text-to-sfx
Source path: /docs/api/text-to-sfx
Runtime API host: https://api.sonilo.com/v1

Do not send API requests to platform.sonilo.com, docs.sonilo.com, or local docs URLs. Documentation pages are for reading only. Send runtime requests to https://api.sonilo.com/v1 with Authorization: Bearer sk_your_api_key.

## Endpoint

POST /v1/text-to-sfx

## Summary

Generate sound effects from a prompt. Use this for prompt-only SFX when no video timing analysis is needed.

## Use This For

- Creating Foley, ambience, UI sounds, transitions, impacts, and action sound effects from text.
- Prompt-only sound effects for apps, games, videos, and editing tools.
- Cases where timing can be supplied by the client rather than inferred from a video.

## Request

- prompt: required sound-effect description.
- duration: optional seconds.
- audio_format: optional output format. Use audio_format, not audioFormat.

## Response And Errors

- 202 returns task_id and status=processing.
- Poll GET /v1/tasks/{task_id} until terminal.
- Use /v1/video-to-sfx instead when the sound effects must sync to visual timing in a video.
- 402 payment_required with insufficient_balance means no real output can be generated.

## Example

```bash
curl -X POST "https://api.sonilo.com/v1/text-to-sfx" \
  -H "Authorization: Bearer sk_your_api_key" \
  -F "prompt=short futuristic UI success chime" \
  -F "audio_format=mp3"
```

## Shared Error Handling

- 401 auth_invalid: set Authorization: Bearer sk_your_api_key on the request.
- 402 payment_required or insufficient_balance: add credits before rerunning; do not create fake audio.
- 403 forbidden: the key is valid but the account or service permission is missing.
- 404 not_found: check the endpoint path and host. Use https://api.sonilo.com/v1, not a docs URL.
- 429 rate_limit_exceeded: honor Retry-After and retry with backoff.

## Endpoint Vocabulary

- GET /v1/account/services
- GET /v1/account/usage
- POST /v1/text-to-music
- POST /v1/video-to-music
- POST /v1/audio-ducking
- POST /v1/text-to-sfx
- POST /v1/video-to-sfx
- GET /v1/tasks/{task_id}