# AI providers

Audoryx ships production runtime adapters and never ships production API keys. Test doubles live only in the automated test suite and are not discoverable provider options.

## Configuration

Use **Admin → AI providers** or environment variables. Database credentials are encrypted by Laravel casts and are write-only in HTTP responses.

### ElevenLabs

The packaged 1.0 adapter uses the official ElevenLabs Music API for complete music generation. Its health check calls `GET /v1/user`, verifies account identity, and reports whether the connected tier exposes music generation. ElevenLabs speech recognition may be used internally for timestamped-lyrics alignment; it is not exposed as a general transcription, TTS, dubbing, sound-effects, isolation, or stem-separation product tool.

Confirm that the connected ElevenLabs account has access to each selected model and that your agreement permits your intended commercial or SaaS use.

### Google Cloud AI

Configure a project, location, and either a service-account JSON document or a short-lived OAuth access token. The adapter exchanges service-account assertions server-side and supports:

- Lyria 2 (`lyria-002`) instrumental music through Vertex AI.
- Lyria 3 Pro Preview (`lyria-3-pro-preview`) complete songs with vocals and user-provided or generated lyrics, up to 184 seconds, through the global Interactions API.
- Lyria 3 Clip Preview (`lyria-3-clip-preview`) 30-second instrumental or vocal song concepts through the global Interactions API.

Lyria 2 produces 32.8-second instrumental WAV output; it does not accept lyrics or generate vocals. Lyria 3 is a Google Preview offering, returns MP3 audio, and uses the `global` region. Audoryx automatically routes Lyria 2 to `:predict` and Lyria 3 to `/v1beta1/.../interactions`. The health check performs a non-billable model preflight. Apply least-privilege IAM, enable the required Google music-generation APIs, and review the Preview offering terms before production use.

### Suno-compatible API (third-party)

This is a configurable third-party adapter. It is not an official Suno integration, and Audoryx is not affiliated with or endorsed by Suno.

The packaged defaults target the independently operated SunoAPI.org-compatible endpoints and can be replaced in the Admin provider settings or environment. Music generation is submitted as an asynchronous task. **Voice to Song is not Text to Speech:** Audoryx uploads the user's recorded vocal file, then calls the compatible `add-instrumental` operation to create a complete arrangement around that performance. The worker polls the configured task-status endpoint until audio is available.

The music endpoint catalogue includes `V4`, `V4_5`, `V4_5PLUS`, `V4_5ALL`, `V5`, and `V5_5`. The compatible Add Instrumental endpoint documents only `V4_5PLUS`, `V5`, and `V5_5`, so Audoryx disables every other model in Voice to Song and enforces that rule again on the server.

Set `SUNO_CALLBACK_URL` to a public HTTPS endpoint accepted by the chosen provider even when Audoryx polling is enabled. Base URL, upload URL, generation paths, status path, health path, models, authentication header, and poll delay are configurable. Commercial rights, data retention, callbacks, rate limits, and OEM/resale permissions depend entirely on the selected third-party contract.

## Runtime behavior

- HTTP connect and response timeouts are configured with `AUDORYX_HTTP_*` values.
- Transient 408/425/429/5xx responses are retried according to the configured attempt count.
- Remote response bodies and credentials are never copied into exceptions or health records.
- Binary outputs are written to the configured private Audoryx media disk and are exposed only through owner/visibility-authorized streaming routes. The Laravel `public` disk is never a valid audio-media target.
- Provider-reported failures transition the generation to `failed` and trigger the existing idempotent credit refund.
- Real health checks update provider status and latency in Admin → AI providers.

## Production checklist

- Restrict each key to the required capabilities.
- Verify webhook signatures and prevent replay.
- Rate-limit by account, user, tool, and provider.
- Use provider idempotency keys when available.
- Apply exponential backoff only to transient errors.
- Do not fail over after a provider may already have accepted a paid request unless idempotency is guaranteed.
- Document which text and audio leave the customer's server.