Chat de IA sobre o mapa real

Um LLM comum responde a uma pergunta sobre Saturno com o que se lembra do signo. POST /v1/ai/chat responde a partir do mapa que acabámos de calcular: posição, casa, aspetos com orbes e janelas de trânsito para os próximos seis meses. A diferença vê-se logo na primeira resposta: não “Saturno em Capricórnio significa disciplina”, mas “Saturno em Capricórnio 25.2° retrógrado, casa 5, conjunção com a Lua orbe 1.7°”.

Experimenta sem chave

A demo funciona sobre um único mapa fixo, 5 perguntas por endereço por dia, com o mesmo prompt de sistema que o endpoint pago. Não é preciso chave.

O que o modelo vê

A demo devolve o campo context: é todo o bloco que foi para o prompt. Aqui está ele a 2 de setembro de 2026 para o mapa da demo (os trânsitos são recalculados em cada pedido, por isso amanhã a lista de janelas será outra):

## 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°)

O bloco está abreviado: na versão completa há 12 planetas e ângulos, até 20 aspetos natais maiores e até 12 janelas de trânsito. O mesmo bloco é montado para o endpoint pago a partir do mapa que tu envias.

O que ele data e o que não data

O nosso prompt de sistema permite indicar meses para os trânsitos que estão no bloco acima e proíbe datar um acontecimento. À pergunta “quando é que me vou casar” o endpoint responde assim (fragmento de uma resposta real de 2 de setembro de 2026):

O Saturno em trânsito forma uma conjunção com a sua Vénus natal. Este trânsito estará ativo durante vários meses: em setembro, outubro, novembro e dezembro de 2026, e também em janeiro, fevereiro e março de 2027, atingindo o orbe mais apertado em março de 2027.

As datas aqui não são inventadas: é a linha transiting Saturn Conjunction natal Venus do bloco de contexto. Uma data de casamento não aparece na resposta e não vai aparecer.

Nota

Se estás a construir um produto em que és tu o responsável pela resposta, este limite trabalha a teu favor: uma previsão datada de um acontecimento, vinda do modelo de outra pessoa, na tua interface, é um risco teu, não nosso. Precisas de uma janela exata em vez de um mês: /v1/transit-calendar.

Personas

persona muda a voz, não os dados. O valor é uma lista fechada, porque a string do corpo do pedido entra no prompt de sistema.

persona	Voz
astrologer	por omissão, como o endpoint respondia antes de o parâmetro existir
plain	sem persona, cumprimento nem assinatura
coach	apoio e o que fazer com isso
teacher	nomeia a técnica e explica os termos

Pergunta “Descreve o meu Saturno num parágrafo”, persona: "coach":

O seu Saturno está no signo de Capricórnio, que é o seu próprio domicílio, e além disso está retrógrado, situado na 5.ª casa. Isto indica um desejo profundamente enraizado de estrutura, disciplina e mestria, sobretudo nas áreas ligadas à autoexpressão, à criatividade, ao romance e aos filhos.

persona: "teacher":

No seu mapa natal, Saturno está em Capricórnio 25.2° (R) na 5.ª casa. Saturno é o planeta da disciplina, da responsabilidade, da estrutura e dos limites; indica as áreas em que procuramos a mestria e enfrentamos as lições da vida.

Uma persona desconhecida dá 400 INVALID_INPUT com a lista de valores permitidos, e não um valor por omissão silencioso.

Pedido e resposta

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'];

Resposta:

{
  "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"
  }
}

reply está aqui abreviado, os restantes campos estão tal como são. model é o fornecedor que respondeu: a cadeia muda sozinha, e o nome aparece na resposta para veres de quem são os tokens que a tua conta contabilizou. Se o modelo atingir o teto de tokens, a resposta é cortada na última frase completa e é acrescentado truncated: true, em vez de se partir a meio de uma palavra.

O mapa é opcional

Sem chart é um chat astrológico comum: não há contexto, o preço é o mesmo. Com chart responde sobre uma pessoa concreta. history com até 10 turnos é enviado pelo cliente: não há sessões do nosso lado, por isso cada turno é autossuficiente e pode ser passado entre processos.

Preço e limites

Preço por turno	100 créditos
A tua própria chave do fornecedor (BYOK)	5 créditos por turno, os tokens são teus
Plano Free	chama sem restrições de plano, dentro de 10 000 créditos por mês
Chaves sandbox aw_test_*	402, porque a sandbox não gasta créditos e o modelo gasta dinheiro
Repetição de um corpo idêntico	da cache, x-cache: HIT, x-credits-used: 0
message	até 2000 caracteres, history até 10 turnos
Idiomas	21, parâmetro language

Cuidado

Ainda não há streaming neste endpoint: a resposta chega inteira. POST /v1/mcp/streaming devolve SSE, mas também espera pela resposta completa e corta-a por frases, por isso não vais ver o primeiro token mais cedo.

Referência completa Esquema do pedido, códigos de erro, exemplos

A tua própria chave do fornecedor X-Provider, X-Provider-Key, 5 créditos por turno

Planos Quantos turnos por mês em cada plano

Agentes de IA e MCP O mesmo chat como ferramenta de um agente