Chat API
Use the OpenAI-compatible Chat Completions endpoint for stateless Ziwei or Qimen requests:
POST https://chat-api.iztro.com/v2/chat/completions
Authorization: Bearer $ZIWEI_API_KEY
Content-Type: application/json
Complete request
curl https://chat-api.iztro.com/v2/chat/completions \
-H "Authorization: Bearer $ZIWEI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "iztro-qimen-v3",
"reasoning_effort": "high",
"max_tokens": 384000,
"language": "en",
"messages": [
{
"role": "user",
"content": "We have discussed a partnership twice, but key terms remain open. Should we push now, continue negotiating, or pause? If it can move forward, give the nearest action windows."
}
],
"metadata": {
"current_datetime": "2026-07-20T14:30:00+08:00"
}
}'
Use iztro-ziwei-v3 for natal and long-range analysis, or iztro-qimen-v3 for one concrete matter at the question time.
Request fields
| Field | Required | Description |
|---|---|---|
model | Yes | iztro-ziwei-v3 or iztro-qimen-v3 |
messages | Yes | OpenAI-compatible conversation messages |
reasoning_effort | No | Standard OpenAI field. Omitted, none, minimal, or low uses the faster non-thinking path; medium, high, xhigh, or max uses the same provider high deep-reasoning path. |
language | No | Response language: zh, en, ko, ja, or vi. Omit it to follow the conversation language automatically. |
stream | No | Set true for SSE token streaming |
max_tokens | No | Optional output ceiling. Omit it to use the current configured maximum of 384,000 output tokens. |
temperature | No | Non-thinking sampling temperature from 0 to 2; cannot be combined with top_p |
top_p | No | Non-thinking nucleus sampling from 0 to 1; cannot be combined with temperature |
frequency_penalty | Unsupported | DeepSeek no longer supports it; requests containing it are rejected |
presence_penalty | Unsupported | DeepSeek no longer supports it; requests containing it are rejected |
tools | No | OpenAI-compatible developer function definitions |
tool_choice | No | Controls developer-supplied tools; it does not select hidden Iztro calculations |
parallel_tool_calls | No | Allows multiple developer tool calls in one turn |
enable_iztro_call | No | Defaults to true; set false to disable hosted Ziwei or Qimen calculations |
metadata.current_datetime | Qimen recommended | User's local ISO 8601 question time with a UTC offset |
metadata.system_prompt_override | No | Application-specific instructions, up to 8,000 characters |
Use the same reasoning_effort field you would send to an OpenAI-compatible Chat Completions endpoint. Do not send a custom thinking field or the Iztro-specific value deep. Reasoning effort does not control answer length; use max_tokens separately.
Non-thinking mode prioritizes speed and can miss or mis-associate details in complex charts. Use reasoning_effort: "high" for cross-palace Ziwei synthesis, multiple fortune layers, and Qimen decisions that combine chart and timing evidence. Deep reasoning is generally more reliable in these cases, although it does not guarantee correctness.
Sampling is available only on the non-thinking path. Set either temperature or top_p, never both. Thinking requests containing either sampling field are rejected because DeepSeek would otherwise ignore it.
These fields are the complete hosted-model request contract. See Model settings for the exact Python and TypeScript SDK names, default behavior, and fields that the upstream Agents SDK exposes but Iztro does not currently use.
When language is set, all user-facing prose and translated astrology terminology use only that language. Canonical code, URLs, model names, tool/event identifiers, and JSON keys remain unchanged.
Response
The response follows the Chat Completions shape. choices[0].message.content contains the answer, usage contains token counts, and the additional iztro_tools array reports the public Iztro calculations used by the hosted model.
For streaming, each SSE chunk uses the Chat Completions chunk shape. Tool activity arrives in iztro_tools before the related answer text.
For durable server-side history, use the Session API or the SDK ChatSession.