Saju API › Saju Interpretation API

Saju Interpretation API

Send a birth date and time with a question: the server calculates the Saju (Four Pillars of Destiny) chart — the Korean system that reads a person from the year, month, day and hour of birth — feeds it to an AI, and the AI returns a reading tailored to the question. The product is called "AI Saju Reading"; "AI Saju Reading · Memory", which remembers the conversation, and "Saju Report", which you get in one go without a question, belong to the same family. Internal prompts and theory are not included in the response — only the interpretation.

Get Started guide Playground Pricing

Three ways to call it

Single consultation POST /reading — one reading for one question. Responses are up to 2,000 characters.
Continued consultation POST /reading/memory — HRUM keeps the conversation memory for each end user, and when they come back the reading picks up the earlier context.
One-shot report POST /reading/report — a report by section, such as overview, wealth, love and 10-year luck cycles, in one go with no question (up to 12 sections).

What you can add

You can add Zi Wei Dou Shu, astrology, Dream Interpretation and Tarot evidence to the reading, or call just one of them with only. The day pillar of the date (today's position in the Saju calendar) is reflected in every reading without a separate call. If you leave out the birth time (hour), the hour pillar is dropped and the reading is based on the three pillars of year, month and day.

Request examples

Single consultation (/reading)

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "올해 이직해도 괜찮을까요?",
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" },
    "maxLength": 600,
    "tone": "warm"
  }'

Continued consultation (/reading/memory)

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading/memory \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "member-1024",
    "question": "지난번에 얘기한 이직 건, 다음 달에 움직여도 될까요?",
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" }
  }'

One-shot report (/reading/report)

curl -X POST https://api.hrum.ai/api/v1/partners/v1/reading/report \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" },
    "sections": ["총평", "재물운", "연애·인연"]
  }'

Authentication uses the X-Partner-Api-Key header, and the base URL is https://api.hrum.ai/api/v1/partners/v1. Python and JavaScript examples and error handling are in the Get Started guide.

Response example (/reading)

{
  "success": true,
  "data": {
    "interpretation": "당신의 사주에서 보이는 특징은...",
    "sajuSource": "computed",
    "usage": {
      "inputTokens": 450,
      "outputTokens": 280
    },
    "costPoints": 18
  }
}

costPoints is the amount deducted for this call. The response fields of the memory and report modes are in the reference.

Pricing

AI Saju Reading costs ₩2,888 per 1M input tokens (excl. VAT; ₩3,177 incl. VAT) and ₩23,100 per 1M output tokens (excl. VAT; ₩25,410 incl. VAT). AI Saju Reading · Memory costs ₩3,754 per 1M input tokens (excl. VAT; ₩4,129 incl. VAT) and ₩30,030 per 1M output tokens (excl. VAT; ₩33,033 incl. VAT). Saju Report is billed by tokens, so there is no fixed price per call; see the pricing table for the expected range. The calculated chart fed to the AI and the system prompt are not charged — only the tokens of the question, the persona and the answer. If you add other items, their evidence blocks are added to the input tokens, plus a fixed fee per item. Only successful calls are deducted from prepaid credits; 4xx and 5xx error responses are not charged.

Store a result once you have it, and reuse it. Sending the same request again is charged again. The same birth date and time with the same options always gives the same result, so save the first response in your database (for example, keyed by a hash of the request body) and use the saved value from then on at no cost. For results that change by date, such as a daily fortune, include the date in the key and reuse the result for that day only.

Full pricing

Full reference

The full parameter table, response field descriptions and error codes are in the reference: AI Saju Reading reference · Memory mode reference · Saju Report reference. Other Saju products are listed under All Saju APIs.

Contact: contact@float.do · Operated by FLOAT Co., Ltd.