Models

Iztro provides two public models through the same Agents SDK and Session API:

iztro-ziwei-v3 starts from a person's birth chart.
iztro-qimen-v3 starts from one concrete decision at the question time.

Choose the model when you create the Agent or Session. If a product needs both perspectives, run the models separately so users can see which model supports each conclusion.

The 30-second rule

Use Ziwei when the question is about a person, relationship, or longer period of life. Use Qimen when the question is about one specific situation happening now. For a Qimen timing question, include the user's local question time with its UTC offset.

Choose the right model

Model	Best for	Required input	Do not use it as
`iztro-ziwei-v3`	Natal personality and strengths, life themes, two-person compatibility, and longer-term fortune cycles	Birth date, birth time, gender, and a clear topic	A chart for an isolated current event with no natal context
`iztro-qimen-v3`	One current decision: whether to proceed, how the situation may develop, what blocks it, and optional timing	The current facts, one decision, and the local question time	A general personality, compatibility, or whole-life reading

Reasoning configuration is model-independent. The same setting works for both Ziwei and Qimen; see Model settings.

`iztro-ziwei-v3`

Choose Ziwei when the answer should be grounded in a birth chart. Common subjects include:

personality, abilities, strengths, and recurring life themes;
career, wealth, relationship, health, or family tendencies;
compatibility between two people, with complete birth details for both;
a defined multi-year period or fortune cycle.

Write a strong Ziwei request

Include:

Whose chart to read. Make it clear whether the subject is the user or another person.
Complete birth details. Provide birth date, birth time, and gender. For compatibility, identify both people separately.
One topic and time horizon. Ask about career, relationship, wealth, or another defined area, and state the years when timing matters.
The desired answer shape. Request a direct conclusion, supporting chart evidence, timing, and practical guidance.

For example:

I was born on 1990-12-21 at 13:00, female. Please analyze my relationship and marriage outlook from 2026 to 2028. Start with the conclusion, then explain the chart evidence, stronger periods, risks, and practical guidance.

Keep follow-up questions about the same person and reading in one ChatSession. Start a separate session when changing to another person's chart or a different compatibility pair.

Ziwei result boundaries

Treat the reading as structured guidance, not a guaranteed event prediction.
Keep every timing statement attached to its stated year or period.
For compatibility, identify which observation belongs to each person and which belongs to the relationship.
Preserve uncertainty when chart signals point in different directions.

`iztro-qimen-v3`

Choose Qimen for a time-sensitive decision about one concrete matter. Good subjects include a partnership, negotiation, interview or offer, launch, trip, dispute, or a specific next step in a relationship.

It does not need a birth date, birth hour, or gender.

Qimen terms in plain language

Term	Meaning
One matter, one chart	Put unrelated decisions in separate requests or sessions.
Question time	The moment the user asks the concrete question, expressed in the user's local timezone.
Yongshen / 用神	The chart symbol used to represent the person, object, or matter being judged.
Yingqi / 应期	Candidate trigger times that support timing analysis; they are not guaranteed outcomes.

Write a strong Qimen request

Include:

One concrete matter. Do not combine unrelated decisions.
Current facts. Explain what has happened, the available choices, and the real constraint.
The decision. Ask whether to proceed, negotiate, wait, stop, or choose between clearly defined options.
Timing, if needed. Explicitly request an action window or likely trigger time.

For example:

We have discussed a distribution partnership twice, but the revenue split and launch date are still open. Should I push for agreement now, continue negotiating, or pause? If the matter can move forward, give me the nearest action windows, the chart evidence, and a practical plan.

Use case	Useful question shape
Partnership or contract	State the negotiation stage and unresolved terms; ask whether to push, renegotiate, or wait.
Interview or offer	State the completed stage and known signals; ask how the process may develop and what to do next.
Launch or event	Name the planned action and constraints; ask whether the current window is suitable and what risk to control.
Relationship decision	Describe the current interaction and one proposed step; ask whether to act now or wait.

Birth details do not improve a Qimen request. If the user also needs a long-term natal view, make a separate Ziwei request and label the two results clearly.

Set the Qimen question time correctly

By default, the service uses the request time. Send current_datetime explicitly for a user in another timezone, a replayed request, a test fixture, or any result that must be reproducible:

2026-07-20T14:30:00+08:00

Use an ISO 8601 timestamp with an explicit UTC offset. This value is the moment the user asks the question, not the planned contract, launch, interview, or travel date. Put planned dates in the prompt.

Keep follow-ups about the same matter in one ChatSession. Start a new session when the user changes to an unrelated matter.

Qimen result boundaries

Timing results are candidate trigger windows, not promises that a contract will be signed, a payment will arrive, or a relationship will succeed.
Keep each date attached to the condition and evidence stated in the answer.
Do not merge dates from different conditions into one “guaranteed success window.”
Keep uncertainty visible and let the user own the real-world decision.

Use either model with the SDK

Install the package and set the server-only ZIWEI_API_KEY as shown in SDK quickstart. In PowerShell, use $env:ZIWEI_API_KEY="sk_ziwei_...".

Model	Python factory	TypeScript factory
`iztro-ziwei-v3`	`iztro_ziwei_agent(...)`	`iztroZiweiAgent({...})`
`iztro-qimen-v3`	`iztro_qimen_agent(...)`	`iztroQimenAgent({...})`

Python
TypeScript

import asyncio
import os

from agents import ModelSettings, Runner
from openai.types.shared import Reasoning
from iztro_agents import iztro_qimen_agent, iztro_ziwei_agent

async def main():
    ziwei = iztro_ziwei_agent(api_key=os.environ["ZIWEI_API_KEY"])
    ziwei_result = await Runner.run(
        ziwei,
        (
            "I was born on 1990-12-21 at 13:00, female. "
            "Analyze my relationship outlook from 2026 to 2028."
        ),
    )

    qimen = iztro_qimen_agent(
        api_key=os.environ["ZIWEI_API_KEY"],
        model_settings=ModelSettings(
            reasoning=Reasoning(effort="high"),
            metadata={"current_datetime": "2026-07-20T14:30:00+08:00"},
            extra_body={"language": "en"},
        ),
    )
    qimen_result = await Runner.run(
        qimen,
        (
            "We have discussed a partnership twice, but key terms remain open. "
            "Should I push now, continue negotiating, or pause? "
            "If it can move forward, give me the nearest action windows."
        ),
    )

    print("Ziwei:", ziwei_result.final_output)
    print("Qimen:", qimen_result.final_output)

asyncio.run(main())

Complete examples:

Ziwei: examples/01_hello_ziwei.py
Qimen: examples/12_qimen_decision.py

import {run} from '@openai/agents';
import {
  iztroQimenAgent,
  iztroZiweiAgent,
} from 'openai-iztro-agents';

const ziwei = iztroZiweiAgent({
  apiKey: process.env.ZIWEI_API_KEY,
});
const ziweiResult = await run(
  ziwei,
  'I was born on 1990-12-21 at 13:00, female. Analyze my relationship outlook from 2026 to 2028.',
);

const qimen = iztroQimenAgent({
  apiKey: process.env.ZIWEI_API_KEY,
  modelSettings: {
    reasoning: {effort: 'high'},
    providerData: {
      language: 'en',
      metadata: {current_datetime: '2026-07-20T14:30:00+08:00'},
    },
  },
});
const qimenResult = await run(
  qimen,
  'We have discussed a partnership twice, but key terms remain open. ' +
    'Should I push now, continue negotiating, or pause? ' +
    'If it can move forward, give me the nearest action windows.',
);

console.log('Ziwei:', ziweiResult.finalOutput);
console.log('Qimen:', qimenResult.finalOutput);

Complete examples:

Ziwei: examples/01-hello-ziwei.ts
Qimen: examples/12-qimen-decision.ts

Use iztro_ziwei_model(...), iztro_qimen_model(...), iztroZiweiModel(...), or iztroQimenModel(...) only when constructing the stock Agent yourself.

Public calculation names

The API and SDK may return the following public values in iztro_tools or the tools array of an Iztro tool event. These values are the complete public naming contract. Do not document or depend on any other tool name or internal implementation detail.

Model	Values that may be returned
`iztro-ziwei-v3`	`iztro-mingpan`; `iztro-daxian`; `iztro-xiaoxian`; `iztro-liunian`; `iztro-liuyue`; `iztro-liuri`
`iztro-qimen-v3`	`qimen-qigua`; `qimen-yingqi`

Ziwei period values can include the requested period after the name, for example iztro-liunian 2026-2028. Display the returned string as-is in developer details. If the product uses friendly progress text, keep that text separate from the returned value.

Use the Session HTTP API

Set model when creating a session:

{
  "external_user_id": "user_42",
  "model": "iztro-ziwei-v3"
}

Use iztro-qimen-v3 instead for one current decision. When sending a Qimen message, current_datetime is a top-level message field:

{
  "message": "Should we push this partnership now, continue negotiating, or pause?",
  "current_datetime": "2026-07-20T14:30:00+08:00",
  "language": "en",
  "enable_iztro_call": true
}

See Session API for the complete request and conversation lifecycle. Configure reasoning independently for either model under Model settings.

Product UX checklist

Show the selected public model name next to the result.
For Ziwei, summarize whose birth details and which time horizon are being analyzed.
For Qimen, show the matter title and local question time with its timezone.
Put the direct conclusion first, then evidence, timing, practical guidance, and uncertainty.
Show public calculation names exactly as returned; never expose or infer internal names.
Present timing as a range or candidate window, never as a guaranteed outcome.
Preserve the original subject so follow-up questions remain tied to the correct person, pair, or matter.

Choose the right model​

iztro-ziwei-v3​

Write a strong Ziwei request​

Ziwei result boundaries​

iztro-qimen-v3​

Qimen terms in plain language​

Write a strong Qimen request​

Set the Qimen question time correctly​

Qimen result boundaries​

Use either model with the SDK​

Public calculation names​

Use the Session HTTP API​

Product UX checklist​