SongVow for AI agents

If you are an AI assistant, shopping agent, or developer building one, this page is for you. It describes how to order a SongVow custom song on behalf of a buyer using three plain JSON endpoints. No API key, no account, no scraping.

What SongVow is

SongVow writes and produces an original song from the buyer's own story about a person: how they met, what makes them special, a favorite memory. The song is delivered in under 30 minutes as a shareable gift page with the lyrics, a player, and on the Ultimate plan a short animated clip made from a photo. Plans are Classic $39, Premium $49, and Ultimate $59. Songs can be written and sung in English or Spanish. 15 occasions are supported, from birthdays and anniversaries to memorials and pet tributes.

How an order works

1. Read the catalog. GET /api/v1/catalog returns the plans, the occasions, and for each occasion the four story questions to ask the buyer, plus the accepted genres, moods and vocal options. Cached for an hour.
2. Collect the story from the buyer. Ask the occasion's questions in your own voice. At least two of the four story fields must have real content. More detail produces a better song; names and specific moments matter most.
3. Create the order. POST /api/v1/orders with the fields below. You get back an order number and a Stripe Checkout URL.
4. Hand the buyer the checkout URL. The buyer pays on Stripe. You never see or handle card details. Once paid, SongVow generates the song and emails the buyer the gift page. You can poll the status endpoint if you want to report progress.

Endpoints

All three endpoints allow cross-origin requests from any domain and return JSON.

Creating an order

Required: occasion, recipientName, senderName, email, plan (classic, premium or ultimate), genre, moods (array), vocal, and at least two of storyBeginning, storySpecial, storyMemory, extra. Optional: pronunciation, avoid, giftMessage, songLanguage (English or Spanish, default English), coupon_code, and the comparison add-on fields compareEnabled, genreB, moodsB, vocalB (+$10, a second version of the same lyrics in a different style; the buyer keeps both).

Every value must come from the catalog. Anything else is rejected with a 400 and a plain-English reason per field, and nothing is created. Send an X-Agent-Name header so we can see which agents are bringing buyers.

POST https://www.songvow.com/api/v1/orders
Content-Type: application/json
X-Agent-Name: your-agent-name

{
  "occasion": "Birthday",
  "recipientName": "Maria",
  "senderName": "Daniel",
  "email": "daniel@example.com",
  "plan": "premium",
  "genre": "Acoustic",
  "moods": ["Romantic", "Nostalgic"],
  "vocal": "Male",
  "songLanguage": "English",
  "storyBeginning": "Maria and I met at a farmers market in 2019. She was buying too many peaches.",
  "storySpecial": "She laughs at her own jokes before she finishes them. She never gives up on anyone.",
  "storyMemory": "Our first road trip to the coast, when the car broke down and we ended up watching the sunset from the hood.",
  "extra": "She is turning 30. Her dog is named Biscuit.",
  "avoid": "Nothing sad, keep it warm and playful",
  "giftMessage": "Happy 30th, Maria. This one is for you."
}

Response (201):

{
  "order_number": "SV-48213",
  "checkout_url": "https://checkout.stripe.com/c/pay/...",
  "payment_required": true,
  "list_price_cents": 4900,
  "currency": "USD",
  "status_url": "https://www.songvow.com/api/v1/orders/SV-48213",
  "status_page": "https://www.songvow.com/order/SV-48213",
  "next_step": "Send the buyer to checkout_url to pay. The song is generated after payment and the buyer is emailed the gift page."
}

Checking status

GET https://www.songvow.com/api/v1/orders/SV-48213

{
  "order_number": "SV-48213",
  "stage": "delivered",
  "paid": true,
  "delivered": true,
  "gift_url": "https://www.songvow.com/gift/SV-48213",
  ...
}

The gift URL is only returned once the song has been delivered. The status endpoint never exposes the story, the lyrics, or the audio file. The buyer's email already contains the gift page link, so polling is optional.

Things worth knowing

Payment. Every paid order goes through Stripe Checkout. The buyer enters their own card on Stripe's page. There is no way to pay through the API itself, by design.

Timing. The song is usually ready within 30 minutes of payment. Ultimate orders with a photo animation can take a little longer.

Revisions. Every plan includes at least one free revision, which the buyer requests from their order page after hearing the song.

Limits. A few orders per IP address per ten minutes. Story fields are limited to 3,000 characters each.

Photos and voice intros. The Ultimate plan's animated photo and the optional recorded voice intro are added by the buyer on their order page after purchase. The API does not accept file uploads.

Questions. Email support@songvow.com. We answer quickly and we are interested in hearing what would make this easier for your agent.