AI-чат на реальній карті

Звичайна LLM відповідає на питання про Сатурна з пам’яті про знак. POST /v1/ai/chat відповідає з карти, яку ми щойно порахували: позиція, дім, аспекти з орбами і транзитні вікна на найближчі пів року. Різниця видно з першої відповіді: не «Сатурн у Козерозі означає дисципліну», а «Сатурн у Козерозі 25.2° ретроградний, 5 дім, кон’юнкція з Місяцем орб 1.7°».

Спробуй без ключа

Демо працює на одній фіксованій карті, 5 питань з адреси на добу, той самий системний промт, що й у платного ендпоінта. Ключ не потрібен.

Що бачить модель

Демо повертає поле context: це весь блок, який пішов у промт. Ось він станом на 2 вересня 2026 для карти з демо (транзити перераховуються на кожен запит, тому список вікон завтра буде іншим):

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

Блок скорочено: у повній версії 12 планет і кутів, до 20 мажорних натальних аспектів і до 12 транзитних вікон. Той самий блок збирається для платного ендпоінта з карти, яку надсилаєш ти.

Що він датує, а що ні

Наш системний промт дозволяє називати місяці для транзитів, які є у блоці вище, і забороняє датувати подію. На питання «коли я вийду заміж» ендпоінт відповідає так (фрагмент справжньої відповіді від 2 вересня 2026):

Транзитний Сатурн формує поєднання з Вашою натальною Венерою. Цей транзит буде активним протягом кількох місяців: у вересні, жовтні, листопаді, грудні 2026 року, а також у січні, лютому та березні 2027 року, досягаючи найтіснішого орбу у березні 2027 року.

Дати тут не вигадані: це рядок transiting Saturn Conjunction natal Venus з блоку контексту. Дати заміжжя у відповіді немає і не буде.

Notatka

Якщо будуєш продукт, у якому за відповідь відповідаєш ти, ця межа працює на тебе: датоване передбачення події від чужої моделі у твоєму інтерфейсі це твій ризик, не наш. Потрібне точне вікно замість місяця: /v1/transit-calendar.

Персони

persona перемикає голос, не дані. Значення закритий перелік, бо рядок з тіла запиту потрапляє у системний промт.

persona	Голос
astrologer	за замовчуванням, як відповідав ендпоінт до появи параметра
plain	без персони, привітання і підпису
coach	підтримка і те, що з цим робити
teacher	називає техніку і пояснює терміни

Питання «Опиши мій Сатурн одним абзацом», persona: "coach":

Ваш Сатурн знаходиться у знаку Козерога, що є його власним домом, і до того ж він ретроградний, розташовуючись у 5-му домі. Це вказує на глибоко вкорінене прагнення до структури, дисципліни та майстерності, особливо у сферах, пов’язаних із самовираженням, творчістю, романтикою та дітьми.

persona: "teacher":

У вашій натальній карті Сатурн знаходиться у Козерозі 25.2° (R) у 5-му домі. Сатурн – це планета дисципліни, відповідальності, структури та обмежень; вона вказує на сфери, де ми прагнемо майстерності та стикаємося з життєвими уроками.

Невідома персона це 400 INVALID_INPUT з переліком допустимих значень, а не тихий дефолт.

Запит і відповідь

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

Відповідь:

{
  "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 тут скорочено, решта полів як є. model це той провайдер, що відповів: ланцюжок перемикається сам, і його назва у відповіді, щоб ти бачив, чиї токени порахував свій рахунок. Якщо модель уперлася в стелю токенів, відповідь обрізається до останнього завершеного речення і додається truncated: true, а не рветься посеред слова.

Карта необов’язкова

Без chart це звичайний астрологічний чат: контексту немає, ціна та сама. З chart він відповідає про конкретну людину. history до 10 ходів надсилає клієнт: сесій на нашому боці немає, тому кожен хід самодостатній і його можна перенести між процесами.

Ціна і ліміти

Ціна ходу	100 кредитів
Свій ключ провайдера (BYOK)	5 кредитів за хід, токени твої
Free-тариф	викликає без обмежень тарифу, у межах 10 000 кредитів на місяць
Sandbox-ключі aw_test_*	402, бо пісочниця не витрачає кредити, а модель витрачає гроші
Повтор ідентичного тіла	з кешу, x-cache: HIT, x-credits-used: 0
message	до 2000 символів, history до 10 ходів
Мови	21, параметр language

Uwaga

Стрімінгу на цьому ендпоінті поки немає: відповідь приходить цілком. POST /v1/mcp/streaming віддає SSE, але теж дочікується повної відповіді і ріже її по реченнях, тому першого токена раніше ти не побачиш.

Повний reference Схема запиту, коди помилок, приклади

Свій ключ провайдера X-Provider, X-Provider-Key, 5 кредитів за хід

Тарифи Скільки ходів у місяць на кожному плані

AI-агенти та MCP Той самий чат як інструмент агента