Chat AI su una carta reale

Un normale LLM risponde a una domanda su Saturno ricordando ciò che sa del segno. POST /v1/ai/chat risponde a partire dalla carta che abbiamo appena calcolato: posizione, casa, aspetti con orbi e finestre di transito per i prossimi sei mesi. La differenza si vede dalla prima risposta: non “Saturno in Capricorno significa disciplina”, ma “Saturno in Capricorno 25.2° retrogrado, casa 5, congiunzione con la Luna orbe 1.7°”.

Prova senza chiave

La demo funziona su un’unica carta fissa, 5 domande per indirizzo al giorno, con lo stesso prompt di sistema dell’endpoint a pagamento. Non serve una chiave.

Cosa vede il modello

La demo restituisce il campo context: è l’intero blocco finito nel prompt. Eccolo, com’era il 2 settembre 2026 per la carta della demo (i transiti vengono ricalcolati a ogni richiesta, quindi domani l’elenco delle finestre sarà diverso):

## Natal Chart
- Sun: Taurus 24.4°, house 9
- Moon: Capricorn 26.9°, house 5
- Saturn: Capricorn 25.2° (R), house 5
- Ascendant: Virgo 20.0°
- Midheaven: Gemini 17.1°

Aspects (computed, use these instead of deriving your own):
- Sun Trine Saturn, orb 0.9°, applying
- Moon Conjunction Saturn, orb 1.7°
- Venus Square Neptune, orb 1.6°

## Transits, computed. Today is 2026-09-02; sampled monthly to 2027-03-01
(These are the only windows that exist. Report a month, not a day.)
- transiting Saturn Conjunction natal Venus: in orb on 2026-09-02, 2026-10-01, 2026-11-01, 2026-12-01, 2027-01-01, 2027-02-01, 2027-03-01 (closest 2027-03-01, orb 0.3°)
- transiting Jupiter Square natal Sun: in orb on 2026-10-01, 2026-11-01, 2026-12-01, 2027-01-01, 2027-02-01, 2027-03-01 (closest 2026-11-01, orb 0.0°)

Il blocco è abbreviato: nella versione completa ci sono 12 pianeti e angoli, fino a 20 aspetti natali maggiori e fino a 12 finestre di transito. Lo stesso blocco viene costruito per l’endpoint a pagamento a partire dalla carta che invii tu.

Cosa data e cosa no

Il nostro prompt di sistema consente di indicare i mesi per i transiti presenti nel blocco qui sopra, e vieta di datare un evento. Alla domanda “quando mi sposerò” l’endpoint risponde così (frammento di una risposta reale del 2 settembre 2026, tradotto):

Saturno di transito forma una congiunzione con la tua Venere natale. Questo transito sarà attivo per diversi mesi: a settembre, ottobre, novembre e dicembre 2026, e poi a gennaio, febbraio e marzo 2027, raggiungendo l’orbe più stretto a marzo 2027.

Le date qui non sono inventate: sono la riga transiting Saturn Conjunction natal Venus del blocco di contesto. Una data di matrimonio nella risposta non c’è e non ci sarà.

Nota

Se costruisci un prodotto in cui della risposta rispondi tu, questo limite lavora a tuo favore: una previsione datata di un evento fatta da un modello altrui nella tua interfaccia è un rischio tuo, non nostro. Ti serve una finestra precisa invece di un mese: /v1/transit-calendar.

Persona

persona cambia la voce, non i dati. Il valore è un elenco chiuso, perché la stringa del body della richiesta finisce nel prompt di sistema.

persona	Voce
astrologer	default, come rispondeva l’endpoint prima dell’arrivo del parametro
plain	senza persona, saluto né firma
coach	sostegno e cosa farne
teacher	nomina la tecnica e spiega i termini

Domanda “Descrivi il mio Saturno in un paragrafo”, persona: "coach":

Il tuo Saturno si trova nel segno del Capricorno, il suo domicilio, ed è per di più retrogrado, collocato nella casa 5. Questo indica un desiderio profondamente radicato di struttura, disciplina e maestria, soprattutto negli ambiti legati all’espressione di sé, alla creatività, al romanticismo e ai figli.

persona: "teacher":

Nella tua carta natale Saturno si trova in Capricorno 25.2° (R) nella casa 5. Saturno è il pianeta della disciplina, della responsabilità, della struttura e dei limiti; indica gli ambiti in cui cerchiamo la maestria e affrontiamo le lezioni della vita.

Una persona sconosciuta è un 400 INVALID_INPUT con l’elenco dei valori ammessi, non un default silenzioso.

Richiesta e risposta

cURL

curl -X POST https://api.astroway.info/v1/ai/chat \
  -H "X-Api-Key: aw_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Що означає моє положення Сатурна?",
    "chart": {
      "date": "1990-05-15",
      "time": "14:30:00",
      "timezoneOffset": 3,
      "latitude": 50.45,
      "longitude": 30.52
    },
    "persona": "plain",
    "language": "uk"
  }'

Node.js

const r = await fetch('https://api.astroway.info/v1/ai/chat', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.ASTROWAY_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Що означає моє положення Сатурна?',
    chart: { date: '1990-05-15', time: '14:30:00', timezoneOffset: 3, latitude: 50.45, longitude: 30.52 },
    persona: 'plain',
    language: 'uk',
  }),
});
const { data } = await r.json();
console.log(data.reply);

Python

import os, requests

r = requests.post(
    'https://api.astroway.info/v1/ai/chat',
    headers={'X-Api-Key': os.environ['ASTROWAY_API_KEY'], 'Content-Type': 'application/json'},
    json={
        'message': 'Що означає моє положення Сатурна?',
        'chart': {'date': '1990-05-15', 'time': '14:30:00', 'timezoneOffset': 3, 'latitude': 50.45, 'longitude': 30.52},
        'persona': 'plain',
        'language': 'uk',
    },
)
data = r.json()['data']
print(data['reply'])

PHP

<?php
use GuzzleHttp\Client;

$aw = new Client(['base_uri' => 'https://api.astroway.info/v1/']);
$r = $aw->post('ai/chat', [
    'headers' => ['X-Api-Key' => getenv('ASTROWAY_API_KEY')],
    'json' => [
        'message' => 'Що означає моє положення Сатурна?',
        'chart' => ['date' => '1990-05-15', 'time' => '14:30:00', 'timezoneOffset' => 3, 'latitude' => 50.45, 'longitude' => 30.52],
        'persona' => 'plain',
        'language' => 'uk',
    ],
]);
$data = json_decode($r->getBody(), true)['data'];
echo $data['reply'];

Risposta:

{
  "ok": true,
  "data": {
    "reply": "Ваш Сатурн знаходиться у знаку Козерога, у 5 домі, і є ретроградним.\n\n**Сатурн у Козерозі** означає, що Сатурн перебуває у своєму домі, де його енергії найсильніші. […] **Місяць у поєднанні з Сатурном (орб 1.7°)**: Це поєднання в Козерозі, у 5 домі, посилює серйозність ваших емоцій та потребу в безпеці.",
    "disclaimer": "Цей текст згенерований ШІ для розваги та саморефлексії. Не є медичною, юридичною чи фінансовою порадою.",
    "model": "gemini-2.5-flash",
    "language": "uk",
    "tokens": { "input": 1822, "output": 758 },
    "duration_ms": 6806,
    "persona": "plain"
  }
}

Qui reply è abbreviato, gli altri campi sono come sono. model è il provider che ha risposto: la catena cambia da sola, e il suo nome è nella risposta perché tu veda di chi sono i token contati nella tua fattura. Se il modello ha raggiunto il tetto dei token, la risposta viene tagliata all’ultima frase completa e si aggiunge truncated: true, invece di interrompersi a metà parola.

La carta è facoltativa

Senza chart è una normale chat astrologica: non c’è contesto, il prezzo è lo stesso. Con chart risponde su una persona concreta. history, fino a 10 turni, lo invia il client: dalla nostra parte non ci sono sessioni, quindi ogni turno è autosufficiente e può essere spostato tra processi.

Prezzo e limiti

Prezzo per turno	100 crediti
La tua chiave del provider (BYOK)	5 crediti per turno, i token sono tuoi
Piano Free	chiamabile senza restrizioni di piano, entro 10 000 crediti al mese
Chiavi sandbox aw_test_*	402, perché la sandbox non consuma crediti, mentre il modello consuma denaro
Ripetizione di un body identico	dalla cache, x-cache: HIT, x-credits-used: 0
message	fino a 2000 caratteri, history fino a 10 turni
Lingue	21, parametro language

Attenzione

Su questo endpoint lo streaming per ora non c’è: la risposta arriva per intero. POST /v1/mcp/streaming restituisce SSE, ma anche lui attende la risposta completa e la spezza per frasi, quindi il primo token non lo vedrai prima.

Reference completa Schema della richiesta, codici di errore, esempi

La tua chiave del provider X-Provider, X-Provider-Key, 5 crediti per turno

Piani Quanti turni al mese su ciascun piano

Agenti AI e MCP La stessa chat come strumento di un agente