Mia
EnglishRoast ModeA playful, affectionate roast of your chart, with real insight behind every joke.
download-url is valid for 24 hours from the time it is issued. Download or save the MP3 before the link expires.The Zodiac Sign Compatibility Audio Report API creates a narrated Western astrology MP3 report from both people’s birth details. It compares two Sun signs through their elements, temperaments and compatibility score. The reading explores where the pair naturally connect, communicate and comfort each other, alongside honest friction points and simple ways to handle them in everyday life.
The API accepts the request immediately and returns a request-id. When the audio is ready, its download-url is delivered by a POST request to the supplied public HTTPS webhook-url. The callback also reports a failed job when generation cannot be completed.
Customize tone, language, voice-id and duration-minutes using the parameter allowed values. Supported durations are 1, 3, 5, 7 and 9 minutes; 3 minutes is the default. The default language follows a supported Accept-Language header, otherwise en.
Authenticate with the x-astrologyapi-key header, or HTTP Basic authentication using userId:apiKey. Send the request body as application/json.
https://audio.astrologyapi.com/v1/western/star-sign-compatibilityx-astrologyapi-keystringrequiredAPI access token used to authenticate requests. Send your access token in this custom header.
namestringrequiredPerson's name, 1–80 characters. The narration addresses the listener by first name.
dayintrequiredDay of month, 1–31. Must form a real calendar date with month and year.
monthintrequiredMonth, 1–12.
yearintrequiredBirth year, for example 1990.
hourintrequiredLocal birth hour, 0–23.
minuteintrequiredLocal birth minute, 0–59.
latitudefloatrequiredBirthplace latitude in decimal degrees, −90 to 90.
longitudefloatrequiredBirthplace longitude in decimal degrees, −180 to 180.
timezonefloatrequiredUTC offset in hours, −12 to 14. Fractional values are allowed, such as 5.5.
genderstringmale, female, or other.
malefemaleotherpartner-namestringrequiredPartner: Person's name, 1–80 characters. The narration addresses the listener by first name.
partner-dayintrequiredPartner: Day of month, 1–31. Must form a real calendar date with month and year.
partner-monthintrequiredPartner: Month, 1–12.
partner-yearintrequiredPartner: Birth year, for example 1990.
partner-hourintrequiredPartner: Local birth hour, 0–23.
partner-minuteintrequiredPartner: Local birth minute, 0–59.
partner-latitudefloatrequiredPartner: Birthplace latitude in decimal degrees, −90 to 90.
partner-longitudefloatrequiredPartner: Birthplace longitude in decimal degrees, −180 to 180.
partner-timezonefloatrequiredPartner: UTC offset in hours, −12 to 14. Fractional values are allowed, such as 5.5.
partner-genderstringPartner: male, female, or other.
malefemaleothertonestringNarration style. Defaults to conversational. See Tones.
conversationaldialoguestorytellerroastcoachcalmbriefingbestiemysticlanguagestringLanguage options are shown as code - language name. Send only the code or a supported language name. Defaults to a supported Accept-Language header, otherwise en. Chinese uses Simplified characters and Mandarin speech.
en - Englishde - Germanfr - Frenches - Spanishpt - Portugueseit - Italianhu - Hungariantr - Turkishro - Romanianel - Greekru - Russianzh - Chinese (Mandarin, Simplified characters)duration-minutesintLength of the audio: 1, 3, 5, 7, or 9. Defaults to 3.
13579voice-idstringVoice choices are shown as voice_name(voice_id) - description. Send the voice ID or name only. Defaults to the voice for the tone. For dialogue, the selected voice is the astrologer and the host uses a voice of the other gender.
oliver(vo-1) - Warm and steady male.emma(vo-2) - Warm, clear and reassuring female.noah(vo-3) - Gentle and unhurried male.grace(vo-4) - Soft and calm female.marcus(vo-5) - Deep and grounded male.leo(vo-6) - Young and lively male.mia(vo-7) - Young and bright female.arthur(vo-8) - Mature and measured male.eleanor(vo-9) - Mature and caring female.webhook-urlstringPublic HTTPS URL that receives the completion or failure callback. Optional in the schema, but supply it to be told when the audio is ready.
Hear how this report sounds in different languages and styles. Play a sample to listen here.
A playful, affectionate roast of your chart, with real insight behind every joke.
A playful, affectionate roast of your chart, with real insight behind every joke.
When audio generation finishes, a POST request with the following JSON body is sent to the public HTTPS webhook-url supplied in your report request. The initial API response only confirms that report generation has started.
Use request-id to match the callback to your original request. A successful callback includes an audio.download-url valid for 24 hours. A failed callback includes a message explaining the failure.
{
"event": "report-audio.completed",
"request-id": "aud-0fdd8705-0a51-41a0-be07-cbed10b6bfe5",
"report-type": "star-sign-compatibility",
"tone": "roast",
"language": "tr",
"duration-minutes": 3,
"voice-id": "vo-7",
"voice-name": "mia",
"status": "completed",
"message": "Your audio is ready. The download-url works without an API key for 24 hours.",
"audio": {
"download-url": "https://audio.astrologyapi.com/a/Y4~aHARdQQ6wc4u2eiIuumrhl-qWK830CNiS1Lkh",
"download-url-expires-at": "2026-10-28T06:36:26.000Z",
"duration-seconds": 181.54
},
"sent-at": "2026-10-27T06:40:12.000Z"
}Return a 2xx response within 10 seconds to confirm receipt. Otherwise, delivery is retried up to five times.
curl --location 'https://audio.astrologyapi.com/v1/western/star-sign-compatibility' \
--header 'Content-Type: application/json' \
--header 'x-astrologyapi-key: <YOUR_ACCESS_TOKEN>' \
--data '{
"name": "Emma Müller",
"day": 15,
"month": 8,
"year": 1990,
"hour": 10,
"minute": 30,
"latitude": 52.52,
"longitude": 13.405,
"timezone": 1,
"gender": "female",
"partner-name": "Luca Rossi",
"partner-day": 3,
"partner-month": 11,
"partner-year": 1992,
"partner-hour": 14,
"partner-minute": 40,
"partner-latitude": 45.4642,
"partner-longitude": 9.19,
"partner-timezone": 1,
"partner-gender": "male",
"tone": "roast",
"language": "tr",
"duration-minutes": 3,
"voice-id": "vo-7",
"webhook-url": "https://example.com/webhooks/audio"
}'
Runs with sample data — no API key needed
{
"request-id": "aud-0fdd8705-0a51-41a0-be07-cbed10b6bfe5",
"report-type": "star-sign-compatibility",
"tone": "roast",
"language": "tr",
"duration-minutes": 3,
"voice-id": "vo-7",
"voice-name": "mia",
"status": "queued"
}