iztro

The iztro Chat API allows for conversational Ziwei or Qimen analysis using a Multi-turn Conversation API. It is recommended to create a session first to preserve context.

Security Note: Always store your API key in a server-side environment variable (e.g., ZIWEI_API_KEY). Never include it in client-side/browser code.

Key Parameters:

• model: Specify iztro-ziwei-v3 or iztro-qimen-v3.
• enable_iztro_call: Set to true to allow the model to call astrology tools.
• current_datetime: (For Qimen) Pass an ISO 8601 string with a UTC offset to ensure chart reproducibility or to handle different timezones.

# 1. Create a session
curl https://chat-api.iztro.com/v2/platform/sessions \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_123",
    "model": "iztro-ziwei-v3",
    "system_prompt_override": "Answer in concise English markdown and suggest possible follow-up questions."
  }'

# 2. Send a message to the session
curl https://chat-api.iztro.com/v2/platform/sessions/{session_id}/messages \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Analyze my 2026 career trend. My birthday is 1995-02-23, birth hour is 17, gender is female.",
    "title": "2026 Career Reading",
    "language": "en",
    "enable_iztro_call": true
  }'

Access Ziwei or Qimen conversational capabilities via HTTP requests. It is recommended to use the multi-turn conversation API: first create a session, then send messages to that session to maintain context.

Note: Always store your API_KEY on the server side; do not include it in client-side/browser code.

# 1. Create a session
curl https://chat-api.iztro.com/v2/platform/sessions \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_123",
    "model": "iztro-ziwei-v3",
    "system_prompt_override": "用簡潔中文回答，避免過度術語，並在最後給出可繼續追問的方向。"
  }'

# 2. Send a message to the session
curl https://chat-api.iztro.com/v2/platform/sessions/{session_id}/messages \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "分析我的 2026 年事業趨勢。生日是 1995-02-23，出生時辰 17 點，性別女。",
    "title": "2026 事業解讀",
    "language": "zh",
    "enable_iztro_call": true
  }'

The Iztro API Full-Stack Demo demonstrates a secure integration pattern where the frontend renders a chatbot while the backend manages the IZTRO_API_KEY. You can choose between a Node.js backend or a Python backend. Both expose the same local API for the frontend to consume.

Prerequisites

• Node.js 20.19+ (required by Vite 8)
• Python 3.10+ (if using the Python backend)

Step 1: Start a Backend

Option A: Node backend

cd backend
npm install
cp .env.example .env
# edit .env and set IZTRO_API_KEY
npm run dev

Note: On Windows PowerShell, use Copy-Item .env.example .env instead of cp.

Option B: Python backend

cd python-backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env and set IZTRO_API_KEY
uvicorn app.main:app --reload --host 0.0.0.0 --port 8787

Note: On Windows PowerShell, activate with .venv\Scripts\Activate.ps1 and use Copy-Item .env.example .env.

Step 2: Start the Frontend

In a separate terminal:

cd frontend
npm install
npm run dev

Open the URL provided by Vite. The frontend defaults to calling port 8787 on the same hostname.

You can access hosted professional AI models via the iztro Chat API. These models automatically call backend astrological tools so you don't have to manage prompts or manual charting.

Available Models

• iztro-ziwei-v3: Best for personality, life patterns, compatibility, and long-term trends (Great Limit, Annual, etc.). Requires birth date, time, gender, and topic.
• iztro-qimen-v3: Best for specific decision-making (negotiations, interviews, etc.). Requires context, a specific question, and the time of inquiry. Does not require birth information.

Integration Pattern

It is recommended to use the multi-turn conversation API: first create a session, then send messages to that session. The API handles context automatically.

Note: Always store your ZIWEI_API_KEY in a server-side environment variable. Never include it in client-side/browser code.

Example: Create a Ziwei Session and Send a Message

# 1. Create a session
curl https://chat-api.iztro.com/v2/platform/sessions \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_123",
    "model": "iztro-ziwei-v3",
    "system_prompt_override": "用简洁中文回答，避免过度术语，并在最后给出可继续追问的方向。"
  }'

# 2. Send a message to the session (replace {session_id} with the ID from step 1)
curl https://chat-api.iztro.com/v2/platform/sessions/{session_id}/messages \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "分析我的 2026 年事业趋势。生日是 1995-02-23，出生时辰 17 点，性别女。",
    "title": "2026 事业解读",
    "language": "zh",
    "enable_iztro_call": true
  }'

Example: Create a Qimen Session

For Qimen, it is recommended to pass current_datetime with a UTC offset to ensure reproducible results.

# 1. Create a session
curl https://chat-api.iztro.com/v2/platform/sessions \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user_123",
    "model": "iztro-qimen-v3"
  }'

# 2. Send a message
curl https://chat-api.iztro.com/v2/platform/sessions/{session_id}/messages \
  -H "Authorization: Bearer $ZIWEI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "我们已经谈过两次渠道合作，但分成和上线时间还没定。现在应该推进、继续谈，还是暂缓？如果可以推进，请给出最近的行动窗口。",
    "current_datetime": "2026-07-20T14:30:00+08:00",
    "language": "zh",
    "enable_iztro_call": true
  }'