A custom-song ordering module for a consumer bot: catalog, order wizard, and a drop-in for the client's platform
The user picks a ready song template, drops in a name — the AI and Suno return a personal track. Shipped as a drop-in module with three clean integration points into the client's platform.
Context
A consumer content bot with a paying audience faces a recurring question: how to add a new revenue vertical without tangling the codebase. A personalized song for a birthday or a wedding is exactly the high-emotion, giftable product that converts in a messenger. Built inline, though, such a feature fuses with the host bot's billing, auth and data model until it can never be moved or replaced in isolation.
The generation side has its own constraint: Suno, the leading model for full songs with vocals, has no official API — everything marketed as one is an aggregator over accounts, able to change response shapes, rate-limit or disappear. The client needed a component that slots into their existing platform and credit economy, handed over with a short integration checklist.
The task
Build a custom-song ordering module a consumer Telegram bot can adopt with minimal surgery, covering two user intents: a fast path — pick a ready template, personalize a name, done — and a from-scratch wizard through occasion, genre, mood and vocal type, with the AI writing the lyrics.
The deliverable is a module, not a product — shipping its own SQL schema in an isolated namespace, its own routers, and a billing stub marked as the single integration point. Two robustness requirements were fixed up front: provider isolation behind one file, and a lyric-generation fallback so the funnel keeps converting during outages.
Approach
The catalog is the core product decision. Instead of asking users to compose from a blank prompt, 1,104 templates were pre-generated from a block system — a matrix of audiences, lyric skeletons and musical spins. Each card is a complete unit: a title, a Suno style string, and finished lyrics with {name} placeholders. The fast path becomes a two-tap purchase; the wizard remains for bespoke orders.
The provider is quarantined by design: the kie.ai aggregator — sharing the account the client already uses for images, so keys and balance stay unified — lives entirely in one kie_suno.py file that submits the task and polls record-info until the track is ready. Lyric generation runs OpenRouter primary with a Gemini backstop, and a database-free preview server lets the client review the product before wiring any infrastructure.
Architecture
Configuration holds reference data — occasions, genres, moods, vocals, packages — and credit pricing; a generator turns block sources into a single catalog.json; a runtime layer handles search, filters, pagination and placeholder rendering. Persistence is a Supabase schema in an isolated suno.* namespace, so module tables never collide with the host's.
The user-facing surface is a Telegram Mini App — a dark vanilla-JS UI over an HTTP API with initData authentication — plus a bot wizard as fallback and launcher. Order logic, the kie callback webhook and the marked billing stub each sit in their own layer; one serve.py runs API, webhook and Mini App together; a separate run.py runs the bot standalone for testing. The integration contract is three documented steps: apply the schema, mount the routers, replace the billing stub.
Result
The module shipped as an integration-ready package — a 1,104-template catalog, two-path ordering, a Telegram Mini App, Suno via kie.ai, lyric generation with fallback — and passed a live end-to-end generation demo. The provider dependency is one file, the database its own namespace, the billing seam a single marked point: a new revenue vertical added without entangling the platform.
Business metrics of the vertical will come from the host platform's analytics once billing is wired in production. The cost side is already known: a track costs $0.01–0.05 to generate against a 30–110 credit price, so unit economics are set by the platform's own pricing, not generation cost.
What we built
Catalog of 1,104 templates
A generator turns block sources (audience × lyric skeleton × musical spin) into catalog.json; each card is a title, a Suno style string, and finished lyrics with {name} placeholders.
Two-path ordering
A fast path — pick a template, personalize a name, done — and a from-scratch wizard through occasion, genre, mood, and vocal, with the AI writing the lyrics.
Telegram Mini App
A premium dark vanilla-JS UI over an HTTP API with Telegram initData auth; a bot wizard serves as the fallback path and Mini App launcher.
Isolated Suno provider
The kie.ai aggregator lives entirely in kie_suno.py: upload, submit, poll record-info until ready, resilient to response-field variation. Switching provider rewrites only this file.
Lyric generation with fallback
OpenRouter as the primary route with a Gemini backstop — the funnel keeps converting when the primary model is down.
Namespaced persistence
A Supabase schema in an isolated suno.* namespace so the module's tables never collide with the host platform's data model.
Three-step integration package
A documented seam: apply the SQL schema, mount the routers into the host FastAPI, replace the billing stub — plus a database-free preview server to review the product first.
Engineering challenges
Suno has no official API
The leading song model exposes only a web app; every "Suno API" is a third-party aggregator. We contained the dependency in a single file that submits and polls the task and tolerates response-field variation, so the aggregator can be swapped without touching the order flow.
A feature that must stay removable
Inline features fuse with the host's billing and data model and become unmovable. The module ships with its own namespaced schema, its own routers, and a single marked billing stub — a small, explicit seam instead of an entanglement.
Provider callback in a polling world
The kie Suno API requires a callback URL even in polling mode. The client always sends one, retrieves the result by polling record-info, and handles the webhook path in production — both completion routes are covered.
Funnel resilience to LLM downtime
Lyric generation on a single model would stall the funnel on any outage. An OpenRouter→Gemini fallback keeps the wizard producing lyrics when the primary provider is unavailable.