🏠 Vastu API and ✋ Palmistry API are now live. Ship them in your app today.

Audio Compatibility

The audio download-url is valid for 24 hours from the time it is issued. Download or save the MP3 before the link expires.

The Compatibility API creates a narrated MP3 report from the supplied birth details. A kundli-matching audio for two people. Send the details of both people (the partner's with the partner- fields) and the audio explains how well they match: the Guna Milan score, how their natures fit together, Manglik status, the best periods for marriage, things to be careful about and simple remedies.

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.

Choose plan as basic or premium, and 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 the Accept-Language header, otherwise hinglish.

For this compatibility report, supply both people’s birth details; the partner’s parameters use the partner- prefix.

Authenticate with the x-astrologyapi-key header, or HTTP Basic authentication using userId:apiKey. Send the request body as application/json.

POSThttps://audio.astrologyapi.com/v1/vedic/compatibility

Authentication

x-astrologyapi-keystringrequired

API access token used to authenticate requests. Send your access token in this custom header.

Body parameters

dayintrequired

Birth day (1–31).

hourintrequired

Birth hour (0–23).

namestringrequired

Name of the person (1–80 characters).

planstring

Voice engine. Default: basic.

  • basic
  • premium
tonestring

Narration style. Default: conversational.

  • conversational
  • dialogue
  • storyteller
  • roast
  • calm
  • news
  • pandit-ji
  • genz
yearintrequired

Birth year.

monthintrequired

Birth month (1–12).

genderstring

Gender of the person.

  • male
  • female
  • other
minuteintrequired

Birth minute (0–59).

languagestring

Audio language. Allowed values are shown as code - language name; send only the code (e.g. hi) or language name (e.g. hindi) in the request. Default: Accept-Language header, otherwise hinglish.

  • hinglish - Hinglish
  • hi - Hindi
  • en - English
  • bn - Bengali
  • mr - Marathi
  • ta - Tamil
  • te - Telugu
  • pa - Punjabi
  • ml - Malayalam
latitudefloatrequired

Latitude of the birth place (-90 to 90).

timezonefloatrequired

Timezone offset from UTC in hours, e.g. 5.5 (-12 to 14).

voice-idstring

Narrator voice. Allowed values are shown as voice_name(voice_id) - description; send only the ID (e.g. vo-1) or voice name (e.g. aarav) in the request. Default: the tone's own voice.

  • aarav(vo-1) - Warm, steady male voice; friendly and reassuring.
  • meera(vo-2) - Warm, reassuring female voice; friendly and clear.
  • ishaan(vo-3) - Gentle, unhurried male voice; soothing.
  • anaya(vo-4) - Soft, calm female voice; soothing.
  • rudra(vo-5) - Deep, authoritative male voice; serious and grounded.
  • kabir(vo-6) - Young, lively male voice; upbeat.
  • tara(vo-7) - Young, bright female voice; upbeat.
  • govind(vo-8) - Mature, wise male voice, like a respected elder.
  • savitri(vo-9) - Mature, caring female voice, like a respected elder.
longitudefloatrequired

Longitude of the birth place (-180 to 180).

partner-dayintrequired

Partner's birth day (1–31).

webhook-urlstring

Public https URL. The result is POSTed to it when the audio is ready. See Webhook.

partner-hourintrequired

Partner's birth hour (0–23).

partner-namestringrequired

Name of the partner (1–80 characters).

partner-yearintrequired

Partner's birth year.

partner-monthintrequired

Partner's birth month (1–12).

partner-genderstring

Gender of the partner.

  • male
  • female
  • other
partner-minuteintrequired

Partner's birth minute (0–59).

duration-minutesint

Requested audio length in whole minutes. Default: 3.

  • 1
  • 3
  • 5
  • 7
  • 9
partner-latitudefloatrequired

Partner's latitude of the birth place (-90 to 90).

partner-timezonefloatrequired

Partner's timezone offset from UTC in hours, e.g. 5.5 (-12 to 14).

partner-longitudefloatrequired

Partner's longitude of the birth place (-180 to 180).

Sample audio

Hear how this report sounds in different languages and styles. Play a sample to listen here.

Tara

MarathiPersonal Astrologer

A warm, personal reading that explains your chart in simple, reassuring words.

Browse all audio samples

Webhook payload

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-3de2e005-e2f5-4e62-aa06-e4d5b4e62cc3",
  "report-type": "compatibility",
  "plan": "basic",
  "tone": "conversational",
  "language": "hinglish",
  "duration-minutes": 5,
  "voice-id": "vo-4",
  "voice-name": "anaya",
  "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.

← Previous
Audio Marriage Timing
Next →
Audio Yearly Life Report
curl --location 'https://audio.astrologyapi.com/v1/vedic/compatibility' \
  --header 'Content-Type: application/json' \
  --header 'x-astrologyapi-key: <YOUR_ACCESS_TOKEN>' \
  --data '{
    "day": 15,
    "hour": 10,
    "name": "Rahul Sharma",
    "plan": "basic",
    "tone": "conversational",
    "year": 1990,
    "month": 8,
    "gender": "male",
    "minute": 30,
    "language": "hinglish",
    "latitude": 28.6139,
    "timezone": 5.5,
    "voice-id": "vo-4",
    "longitude": 77.209,
    "partner-day": 2,
    "webhook-url": "https://example.com/webhooks/audio",
    "partner-hour": 18,
    "partner-name": "Priya Verma",
    "partner-year": 1992,
    "partner-month": 11,
    "partner-gender": "female",
    "partner-minute": 10,
    "duration-minutes": 5,
    "partner-latitude": 19.076,
    "partner-timezone": 5.5,
    "partner-longitude": 72.8777
}'
Try it

Runs with sample data — no API key needed

{
  "request-id": "aud-3de2e005-e2f5-4e62-aa06-e4d5b4e62cc3",
  "report-type": "compatibility",
  "plan": "basic",
  "tone": "conversational",
  "language": "hinglish",
  "duration-minutes": 5,
  "voice-id": "vo-4",
  "voice-name": "anaya",
  "status": "queued"
}