> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/sonic-api-reference/provider-connections-and-kie.ai.md). # Provider Connections & Kie.ai Canonical provider-account layer for Kie.ai and Suno Direct, including encrypted BYOK, managed credentials, callbacks, provider credits and cost reconciliation. **Status:** `Canonical / v1.3` Kie.ai is a provider account layer beneath the provider-independent SONIC API. The public application contract does not expose Kie task IDs as business identities. ### Provider topology ``` SONIC public API │ ▼ Provider Router ├── KIE │ ├── SONIC_MANAGED │ └── CUSTOMER_BYOK └── SUNO_DIRECT ├── SONIC_MANAGED └── CUSTOMER_BYOK ``` Provider API keys are encrypted at rest and remain server-only. ### Kie configuration ``` Base URL: https://api.kie.ai Authentication: Authorization: Bearer Credit balance: GET /api/v1/chat/credit Music create: POST /api/v1/generate ``` Kie provider credit balance is stored as a `ProviderBalanceSnapshot`. It is never represented as a SONIC AI Credit balance. ### Provider connection endpoints ```http GET /api/v1/providers GET /api/v1/providers/credentials POST /api/v1/providers/credentials GET /api/v1/providers/credentials/{credentialId} DELETE /api/v1/providers/credentials/{credentialId} POST /api/v1/providers/credentials/{credentialId}/validate POST /api/v1/providers/credentials/{credentialId}/balance ``` Provider credential responses are redacted. Plaintext provider secrets are never returned after submission. ### BYOK workflow ``` Settings → API → Provider Connections → Kie.ai → Connect ``` SONIC validates a submitted Kie key by requesting the provider credit balance, encrypts the key using the provider-credential vault, stores only a non-secret fingerprint/display suffix, and records the health/balance snapshot. A Kie webhook HMAC key can be encrypted independently from the API key for callback verification. ### Billing modes ``` SONIC_MANAGED BYOK BYOK_WITH_SONIC_FALLBACK ``` For BYOK, Kie provider credits are charged to the customer's external Kie account while SONIC orchestration may still consume SONIC AI Credits according to the pricing catalog. Hybrid fallback is explicit. An invalid or exhausted BYOK credential can fall back to the approved SONIC-managed route only when the request selected `BYOK_WITH_SONIC_FALLBACK`. ### Kie scheduler Provider rate limiting is independent of SONIC public API limits. ``` SONIC API rate policy ↓ provider/account scheduler ↓ Kie create endpoint ``` The default Kie scheduler reserve in the v1.3 implementation is 18 creates per 10 seconds per provider account, leaving headroom below the currently documented Kie account creation ceiling. A documented HTTP 429 rejection is retryable because it did not enter the provider queue. An ambiguous network/timeout during create is **not** blindly dispatched again because a provider task may already exist. ### Callback verification Kie callbacks are the primary state path. SONIC validates the documented HMAC-SHA256 signature using the callback timestamp and provider task ID, enforces a timestamp-skew window, performs a constant-time comparison, writes a durable callback receipt/job and acknowledges quickly. ``` Kie callback → HMAC validation → durable receipt / dedupe → fast acknowledgement → async normalize → monotonic GenerationOperation merge ``` Polling is centralized recovery only. Clients never poll Kie independently. ### Provider usage Provider task observations normalize into `ProviderUsageEvent` records. When the provider response includes `creditsConsumed`, SONIC treats it as a provider-cost reconciliation signal. ``` SONIC PricingCatalog → customer quote/reservation → provider execution → provider creditsConsumed (when available) → cost reconciliation → SONIC settlement ``` Reconciliation status can be `MATCHED`, `UNDER_EXPECTED`, `OVER_EXPECTED` or `UNKNOWN`. Excess drift emits `PROVIDER_COST_DRIFT` for Finance/Admin monitoring. ### Result retention boundary Provider URLs are temporary delivery artifacts, not durable SONIC assets. ``` provider result URL → SONIC ingestion worker → download + validate → SONIC-controlled object storage → durable Asset ``` The ingestion job runs as soon as a successful result is observed. Application state references the durable SONIC asset, not the provider URL. ### Provider error normalization Examples include `PROVIDER_CREDENTIAL_INVALID`, `PROVIDER_CREDITS_EXHAUSTED`, `RATE_LIMITED`, `PROVIDER_UNAVAILABLE`, `PROVIDER_TIMEOUT`, `INVALID_INPUT`, `CONTENT_POLICY_REJECTED`, `GENERATION_FAILED`, `CALLBACK_FAILED` and `RESULT_EXPIRED`. Original provider codes/messages remain internal diagnostics and do not leak credentials or raw provider responses. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/sonic-api-reference/provider-connections-and-kie.ai.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.