Sonica API v1

All supported public endpoints are under /api/v1. Keep API keys on your backend and never expose them in browser or mobile client code.

Authorization: Bearer sv_live_xxxxxxxxxxxxxxxx_secret
Content-Type: application/json
Idempotency-Key: order_12345

Every response includes an X-Request-Id. Store it with your logs for support and troubleshooting.

POST /api/v1/generations

{
  "prompt": "An uplifting electronic pop song with female vocals",
  "language": "en",
  "external_reference": "order_12345",
  "metadata": { "customer_id": "cus_4829" }
}

The endpoint returns 202 Accepted. Save the generation ID and poll the status endpoint every 5 to 15 seconds.

{
  "id": "gen_01abc...",
  "status": "queued",
  "created_at": "2026-07-16T10:30:00Z",
  "estimated_credits": 1,
  "external_reference": "order_12345"
}

GET /api/v1/generations/{generationId}
GET /api/v1/generations?external_reference=order_12345&limit=20

Stop polling at completed, failed, or cancelled. Completed responses include available title, audio, image, and lyrics fields.

GET /api/v1/credits/balance

Use an Idempotency-Key for generation creation. Retrying the same payload and key returns the original accepted response; reusing the key with a different payload returns 409.

Failed generation jobs automatically restore reserved credits. A successful generation captures the estimated credit cost shown in the accepted response.

{
  "error": {
    "type": "invalid_request_error",
    "code": "VALIDATION_ERROR",
    "message": "Invalid request.",
    "param": "prompt",
    "request_id": "req_abc123"
  }
}

API v1 endpoints are currently limited to 100 requests per minute per authenticated user per endpoint. Back off after 429. Other common responses are 400, 401, 402, 403, 404, 409, 422, and 503.

1. Store your API key only on a trusted backend.
2. Check credit balance when preflight validation is useful.
3. Create generations with a stable idempotency key.
4. Persist the generation ID and your external reference.
5. Poll status every 5 to 15 seconds until terminal.
6. Store completed output URLs promptly according to your retention needs.
7. Log request IDs and handle retryable failures with bounded backoff.

Third-party webhooks are not available in the current v1 release. Polling is the supported integration model.