AI Summary

Every calculation returns dozens of interpretation texts. An AI summary turns the most significant of them into a few sentences about what the horoscope actually means for the person — or, for synastry and composite, for the two people together.

Summaries are not generated during a calculation. The calculation hands you a signed link, and only opening that link runs the model.

Required Module

Requires the ai:summary module, included in the Premium and Deluxe plans. It is not sold separately.

You also need the interpretation texts of the horoscope type you are summarizing (for example natal:texts) — without texts there is nothing to summarize.

How it works

1. You call a calculation endpoint as usual.
2. The response contains a summary object with a signed URL.
3. You open that URL when — and if — you want the summary.

Nothing is calculated, stored or charged in step 1 and 2. That is deliberate: a horoscope call should not pay for a feature most callers never use.

The summary link

{
    "data": {
        "points": { "...": "..." },
        "aspects": [],
        "chart": { "url": "https://api.astroapi.cloud/api/chart2/natal.svg?..." },
        "summary": {
            "url": "https://api.astroapi.cloud/api/calc/natal/summary?t=eyJ0Ijoi...&expires=1793000000&sig=Ab3...",
            "method": "GET",
            "cost": 10,
            "expiresAt": "2026-08-30T10:00:00Z"
        }
    }
}

Field	Description
url	Signed URL that returns the summary. Carries the whole request, so no body is needed.
method	Always GET.
cost	API requests charged when the summary is generated. A cached summary costs 1.
expiresAt	The link stops working after 7 days. Re-run the calculation for a fresh one.

The summary object is only present when your subscription includes the module. If it is missing, check your plan.

Store the link, not just the chart

The link expires after 7 days and it is signed for exactly one chart. It cannot be edited: changing the birth data, the horoscope type or the organization in the URL invalidates the signature.

Getting the summary

curl "https://api.astroapi.cloud/api/calc/natal/summary?t=eyJ0Ijoi...&expires=1793000000&sig=Ab3..." \
  -H "X-Api-Key: your-api-key"

The signature makes the API key optional, so the link also works from a browser or an embed that cannot set headers. When you do send a key, it must belong to the same organization the link was issued to.

This takes a while

Generating a summary runs the calculation again, fetches the texts and calls a language model. Expect several seconds. A summary that was generated before returns immediately.

Response

{
    "data": {
        "horoscopeType": "natal",
        "language": "en",
        "summary": "You lead with visibility rather than caution: the Sun in Leo in the tenth house puts your work and your reputation at the centre of how you understand yourself…",
        "cached": false,
        "generatedAt": "2026-08-23T10:15:22Z",
        "model": "@cf/qwen/qwen3-30b-a3b-fp8",
        "highlights": [
            { "kind": "point", "label": "Sun in Leo in house 10" },
            { "kind": "point", "label": "Moon in Taurus in house 7" },
            { "kind": "aspect", "label": "Sun square Saturn (orb 0.4°)" }
        ]
    }
}

Field	Description
summary	The generated text, 4 to 6 sentences.
cached	true when served from cache. Cached summaries count as 1 request instead of 10.
highlights	The placements the summary was written from, strongest first.
model	The model that wrote the text.

Supported horoscope types

Type	Endpoint	What the summary is about
natal	/api/calc/natal/summary	Who this person is
synastry	/api/calc/synastry/summary	What these two people do to each other
composite	/api/calc/composite/summary	The relationship the two of them form
transit	/api/calc/transit/summary	The period ahead
solar	/api/calc/solar-return/summary	The year ahead
lunar	/api/calc/lunar-return/summary	The month ahead
progressions	/api/calc/progressions/summary	The phase of life this person is in

What goes into the summary

A full natal chart yields 40+ interpretation texts. Feeding all of them to a model produces a listing, not a reading — and costs far more. Instead, the placements are scored and only the strongest survive:

• Placements — the luminaries and the Ascendant weigh heaviest, then the chart ruler, personal planets, and anything in an angular house.
• Aspects — scored on exactness (how tight the orb is relative to that aspect's maximum), on how major the aspect is, and on how personal the two ends are. An exact Sun–Saturn square outranks a wide Neptune–Pluto sextile by a wide margin.
• Synastry keeps only cross-aspects, in both directions, tagged by whose planet acts on whose chart.
• Transits additionally include the houses transiting planets are moving through.

Scoring is deterministic: the same chart always produces the same selection, which is what makes the result cacheable.

The model may only use the texts it is given. It does not invent placements, dates or advice — so a summary reflects your own interpretation texts, including any you edited yourself with the Content Editor.

Language

The summary is written in the language of the calculation. Pass language on the calculation request and the link carries it:

curl -X POST "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "dateTime": "1990-06-15T14:30",
    "location": { "longitude": 4.89, "latitude": 52.37, "timezone": "Europe/Amsterdam" },
    "language": "nl",
    "includeText": true
  }'

The interpretation texts are already localized, and the model is instructed to write in the same language.

What it costs

Situation	API requests
Calculation with a summary link in the response	1 (unchanged)
Opening the link, summary generated	10
Opening the link, summary already cached	1
The request failed (403, 422, expired link)	0

Generated summaries are cached for 30 days per chart, language and prompt version, so repeatedly opening the same link is cheap.

The X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset response headers reflect the weighted cost, and so does the usage reporting in the dashboard.

Errors

Status	Meaning
400	The link is malformed or the token does not belong to this horoscope type.
401	The signature is invalid or the link expired.
403	Your subscription lacks ai:summary or the interpretation texts of this type, or the link belongs to another organization.
409	A summary for this chart is already being generated. Retry in a few seconds — this stops you paying twice for the same text.
422	No interpretation texts are available for this chart, so there is nothing to summarize.

Next Steps

• Content & Interpretations — the texts a summary is written from
• Modules — what your plan includes
• Rate Limits — quotas and weighted requests