✋ Palmistry API and 🎧 Audio Reports API are now live. Ship them in your app today.

Personal Transit Audio Forecast

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 Personal Transit Audio Forecast API creates a narrated Western astrology MP3 report from the supplied birth details. It explains the next three months of planetary movement over the person’s birth chart, including when each important transit begins and peaks. The reading connects these periods to the life areas they affect and describes what each transit asks of the person.

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.

POSThttps://audio.astrologyapi.com/v1/western/transit-report

Authentication

x-astrologyapi-keystringrequired

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

Body parameters

namestringrequired

Person's name, 1–80 characters. The narration addresses the listener by first name.

dayintrequired

Day of month, 1–31. Must form a real calendar date with month and year.

monthintrequired

Month, 1–12.

yearintrequired

Birth year, for example 1990.

hourintrequired

Local birth hour, 0–23.

minuteintrequired

Local birth minute, 0–59.

latitudefloatrequired

Birthplace latitude in decimal degrees, −90 to 90.

longitudefloatrequired

Birthplace longitude in decimal degrees, −180 to 180.

timezonefloatrequired

UTC offset in hours, −12 to 14. Fractional values are allowed, such as 5.5.

genderstring

male, female, or other.

  • male
  • female
  • other
tonestring

Narration style. Defaults to conversational. See Tones.

  • conversational
  • dialogue
  • storyteller
  • roast
  • coach
  • calm
  • briefing
  • bestie
  • mystic
languagestring

Language 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 - English
  • de - German
  • fr - French
  • es - Spanish
  • pt - Portuguese
  • it - Italian
  • hu - Hungarian
  • tr - Turkish
  • ro - Romanian
  • el - Greek
  • ru - Russian
  • zh - Chinese (Mandarin, Simplified characters)
duration-minutesint

Length of the audio: 1, 3, 5, 7, or 9. Defaults to 3.

  • 1
  • 3
  • 5
  • 7
  • 9
voice-idstring

Voice 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-urlstring

Public HTTPS URL that receives the completion or failure callback. Optional in the schema, but supply it to be told when the audio is ready.

Sample audio

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

Mia

EnglishTwo-Host Podcast

A host and astrologer explore your chart in an engaging podcast-style conversation.

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-12fe2a97-5d9f-4d45-9432-7a050bc217d9",
  "report-type": "transit-report",
  "tone": "dialogue",
  "language": "zh",
  "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.

← Previous
12-Month Astrology Audio Forecast
Next →
Birthday Year Audio Forecast
curl --location 'https://audio.astrologyapi.com/v1/western/transit-report' \
  --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",
    "tone": "dialogue",
    "language": "zh",
    "duration-minutes": 3,
    "voice-id": "vo-7",
    "webhook-url": "https://example.com/webhooks/audio"
}'
Try it

Runs with sample data — no API key needed

{
  "request-id": "aud-12fe2a97-5d9f-4d45-9432-7a050bc217d9",
  "report-type": "transit-report",
  "tone": "dialogue",
  "language": "zh",
  "duration-minutes": 3,
  "voice-id": "vo-7",
  "voice-name": "mia",
  "status": "queued"
}