คู่มือ API

หากอยากรู้ว่าสแตก API นี้ทำงานอย่างไรในบริการจริง — ลองใช้การวิเคราะห์ซาจูและการสนทนากับ AI ด้วยตัวเองได้ที่ INTA แอป AI ซาจูที่ขับเคลื่อนด้วยเอนจินเดียวกัน INTA คือข้อมูลอ้างอิงที่มีชีวิตของ API นี้ การตอบกลับด้วยเสียง AI (TTS) ของ INTA ก็ขับเคลื่อนด้วยสแตกเดียวกัน — API เสียงจะเปิดให้ใช้ในภายหลัง

Quickstart

HRUM ให้บริการ AI ที่จดจำได้ การวิเคราะห์ซาจู และการขายต่อ LLM ทำตาม 3 ขั้นตอนต่อไปนี้:

ที่อยู่หลักคือ https://api.hrum.ai (API) · https://console.hrum.ai (คอนโซล) ที่อยู่เดิม api.float.do · console.float.do · api.inta.do ยังใช้งานได้ตามเดิม หากเชื่อมต่อไว้แล้วก็ไม่ต้องเปลี่ยน

1. ออกคีย์ API - สมัครสมาชิกคอนโซลแล้วออกคีย์ที่หน้า คีย์ API (คีย์จะแสดงเพียงครั้งเดียวทันทีหลังออก) ขั้นตอนตั้งแต่สมัครสมาชิกจนถึงการจัดการข้อผิดพลาดสรุปไว้ใน คู่มือเริ่มต้นใช้งานสำหรับนักพัฒนา
2. ส่งคำขอ - ส่งคำขอ POST ตามตัวอย่างด้านล่าง
3. จัดการการตอบกลับ - ดึงข้อมูลซาจูจากการตอบกลับ JSON

curl -X POST https://api.hrum.ai/api/v1/partners/v1/manseryeok \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1990,
    "month": 1,
    "day": 15,
    "hour": 14,
    "minute": 30,
    "timezone": "Asia/Seoul",
    "gender": "male"
  }'

ข้อควรระวังเรื่อง User-Agent: User-Agent เริ่มต้นของไลบรารีมาตรฐาน Python urllib (Python-urllib/3.x) จะติดกฎความปลอดภัยและได้ 403 (error 1010) กลับมา requests, OpenAI SDK, Node, curl ทำงานได้ปกติ หากใช้ urllib หรือ HTTP client ที่เขียนเอง ให้ระบุเฮดเดอร์ User-Agent: <ชื่อแอป>/<เวอร์ชัน> เอง (วัดจริง: python-requests ผ่าน · OpenAI/Python ผ่าน · node ผ่าน · Python-urllib 403)

ประหยัดค่าใช้จ่าย — เก็บผลลัพธ์ไว้แล้วนำกลับมาใช้ ทุกคำขอที่สำเร็จจะคิดค่าบริการแยกกัน ผลปฏิทินหมื่นปี · จื่อเวยโต่วซู่ · ดวงสมพงษ์ · โหราศาสตร์ตะวันตก · ดวงชะตาตลอดชีวิตที่มีวันเวลาเกิดและตัวเลือกเดียวกันจะได้ผลเหมือนเดิมแม้เรียกใหม่ จึงควรเก็บการตอบกลับแรกลง DB (เช่น ใช้แฮชของเนื้อหาคำขอเป็นคีย์) แล้วใช้ค่าที่เก็บไว้ในครั้งต่อไป สำหรับผลที่เปลี่ยนตามวันที่ เช่น ดวงวันนี้หรือกราฟดวงชะตา ให้ใส่วันที่ลงในคีย์ด้วย รายละเอียดอยู่ที่ Idempotency

ข้อมูลอ้างอิง API

HRUM ให้บริการ AI ที่จดจำได้ การวิเคราะห์ซาจู และการขายต่อ LLM

• เปลี่ยนแปลง (2026-10-14): ปรับสำนวนประโยคตอบกลับภาษาเกาหลีให้เป็นแบบสุภาพ (해요체) เหมือนกันทั้งหมด (ไม่มีการเปลี่ยนเนื้อหาหรือฟิลด์)
• เพิ่ม (2026-10-14): หากไม่รู้จักชื่อเขตเวลา การตอบกลับที่สำเร็จจะมี warnings (UNKNOWN_TIMEZONE) แนบมา การคำนวณยังใช้เขตเวลาเริ่มต้นเหมือนเดิม และถ้าไม่มีคำเตือน การตอบกลับจะเหมือนเดิม — คำเตือนในการตอบกลับ
• เพิ่ม (2026-10-17): birth ของ AI อ่านดวงซาจู · หน่วยความจำการอ่านดวง · รายงาน รับฟิลด์สถานที่เกิด · เขตเวลา · เดือนอธิกมาส (isLeapMonth · timezone · พิกัด · country · zaSiRule · birthTimePrecision) เหมือนกับ API ปฏิทินหมื่นปี หากไม่ส่ง การคำนวณจะเหมือนเดิม — API AI อ่านดวงซาจู

RIDM Memory API

โฮสต์ความจำการสนทนาแยกตามผู้ใช้ปลายทาง และเพิ่มเลเยอร์หน่วยความจำให้โมเดล ridm/* หน่วยความจำใช้ได้เฉพาะ ridm/* ส่วนโมเดล OpenAI/Google เป็นการขายต่อ (ตามต้นฉบับ) — โมเดลเดียวกัน แต่เป็นสินค้าต่างกัน รองรับการแทรกคำบรรยาย YouTube อัตโนมัติด้วย

ไม่มีเซสชัน — เซสชันไม่จำกัด เมื่อเรียกด้วย user เดียวกัน การสนทนาจะต่อเนื่องไปไม่สิ้นสุด ทุกครั้งที่เรียก เซิร์ฟเวอร์จะแนบเทิร์นสนทนาล่าสุด historyCount เทิร์น และความจำระยะยาว recallCount รายการ (สรุป · โปรไฟล์ · ข้อเท็จจริงที่จำไว้ · เรื่องที่กำลังกังวลอยู่) ให้อัตโนมัติ พาร์ทเนอร์จึงส่งแค่ข้อความใหม่ข้อความเดียว ปรับระยะการอ้างอิงย้อนหลังได้ด้วยตัวเลขสองตัวนี้ และกำหนดเพดานจำนวนข้อความที่เก็บต่อผู้ใช้ปลายทางด้วย memoryCap หากต้องการจัดการประวัติเอง ให้ละ historyCount แล้วใส่บทสนทนาก่อนหน้าใน messages ตามแบบ OpenAI

บทสนทนายาวก็ไม่ทำให้ค่าใช้จ่ายเพิ่มแบบเส้นตรง เทิร์นของผู้ช่วยที่เก่าจะถูกบีบอัดอัตโนมัติ — 2 เทิร์นล่าสุดคงต้นฉบับไว้ ก่อนหน้านั้นจะลดเป็นขั้นจาก 500 ตัวอักษร → 200 ตัวอักษรเพื่อประหยัดโทเค็นขาเข้า (เทิร์นของผู้ใช้คงเดิม) และสำหรับคำถามที่ถามถึงสิ่งที่เคยพูด เช่น "ครั้งก่อนบอกว่า ~ ไม่ใช่เหรอ" เซิร์ฟเวอร์จะค้นหาบทสนทนาจริงที่เก็บไว้แล้วอ้างอิงพร้อมวันที่และผู้พูด (รวมอยู่ใน recalledMemories) — ถ้าไม่มีบันทึกก็จะตอบว่าไม่มี ไม่แต่งขึ้นเอง

LLM API (ขายต่อ) vs RIDM Memory API — ต่างกันอย่างไร

โมเดลเดียวกัน สินค้าต่างกัน — ต่างกันแค่คำนำหน้า ที่เหลือเหมือนกัน หากการตอบกลับมี recalledMemories · memorySaved แนบมา แสดงว่าเป็นเส้นทาง RIDM

เปรียบเทียบตัวอย่างโค้ด

// LLM API (resale) — no memory
{
  "model": "openai/gpt-5.6-terra",
  "messages": [{ "role": "user", "content": "..." }]
}

// RIDM Memory API — with the memory engine
{
  "model": "ridm/gpt-5.6-terra",  // only the prefix differs
  "user": "user_123",              // required (keeps memory)
  "messages": [{ "role": "user", "content": "..." }]
}

// Difference in the response
// Resale: { "id": "...", "choices": [...], "usage": {...}, "costWon": 1, "costUsd": 0.00045 }
// RIDM: { "id": "...", "choices": [...], "usage": {...}, "costWon": 2, "recalledMemories": [...], "memorySaved": { "id": "turn-...", "keywords": [] } }

POST /api/v1/partners/v1/chat/completions

การเรียก LLM แบบสนทนาที่มีหน่วยความจำ เมื่อเรียกด้วย user/endUserId เดียวกัน บริบทในอดีตจะถูกคงไว้

พารามิเตอร์คำขอ

ตัวอย่างคำขอ

curl -X POST https://api.hrum.ai/api/v1/partners/v1/chat/completions \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ridm/gpt-5.6-terra",
    "user": "member-1024",
    "messages": [
      { "role": "user", "content": "Can we pick up where we left off about changing jobs?" }
    ]
  }'

ตัวอย่างการตอบกลับ

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1629292800,
  "model": "ridm/gpt-5.6-terra",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "안녕하세요! 이전 대화를 기억하고 있어요..."
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 320,
    "prompt_tokens_details": { "cached_tokens": 0 }
  },
  "costWon": 45,
  "recalledMemories": [...],
  "memorySaved": { "id": "turn-1756200000000", "keywords": [] },
  "youtubeUsed": ["abc123def45"]
}

usage ไม่มี total_tokens — จะมี prompt_tokens, completion_tokens, prompt_tokens_details.cached_tokens และถ้าเป็นโมเดลให้เหตุผลจะมี completion_tokens_details.reasoning_tokens (รวมอยู่ใน completion_tokens แล้ว) memorySaved คืออ็อบเจกต์ข้อมูลเทิร์นที่เก็บ หรือ null (เกินเพดาน · เทิร์นที่เรียกเครื่องมือ) youtubeUsed คืออาร์เรย์ ID วิดีโอที่แทรกคำบรรยาย (ไม่ใช่ URL)

รูปแบบสตรีมมิง (SSE)

เมื่อ stream: true จะตอบกลับเป็นอีเวนต์ SSE ที่มีชื่อ ไม่ใช่รูปแบบ chunk ของ OpenAI ดังนั้นใช้ตัวแยกวิเคราะห์สตรีมของ OpenAI SDK อ่านไม่ได้ — ให้แยกวิเคราะห์ SSE เอง (การตอบกลับแบบไม่สตรีมเข้ากันได้กับ OpenAI)

event: chunk
data: {"delta":"안녕하세요"}

event: message_done
data: {"finish_reason":"stop","usage":{"prompt_tokens":1250,"completion_tokens":320,"prompt_tokens_details":{"cached_tokens":0}},"costWon":45,"recalledMemories":[],"memorySaved":{"id":"turn-1756200000000","keywords":[]}}

data: [DONE]

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไปแล้ว นี่คือรหัสที่ API นี้ส่งออกมา ข้อผิดพลาดที่เกิดหลังเริ่มตอบกลับใน stream: true จะมาเป็น event: error ({message, code, status}) โมเดลขายต่อก็ใช้ตารางเดียวกัน

ข้อควรระวัง

• การแทรกคำบรรยาย YouTube: เมื่อ youtube:true จะดึงคำบรรยายจากลิงก์ YouTube ในข้อความสุดท้ายแล้วรวมเข้าในโทเค็นขาเข้า หากดึงคำบรรยายไม่ได้ การสนทนาจะดำเนินต่อโดยไม่แทรก และ youtubeUsed ในการตอบกลับจะเป็นอาร์เรย์ว่าง (เฉพาะ API สรุป YouTube แบบเดี่ยวที่ได้ 400 และไม่คิดค่าบริการ)
• เข้ากันได้กับโมเดลต้นฉบับ: หากระบุค่า model เป็น openai/* หรือ google/*, anthropic/* จะเรียกโมเดลต้นฉบับตามเดิมโดยไม่มีฟีเจอร์หน่วยความจำ (ต้นทุน × อัตราแลกเปลี่ยน × 1.10)
• ส่วนลดแคชพรอมต์: โมเดลตระกูล OpenAI (openai/*, ridm/gpt-*) หากส่งส่วนต้นที่เหมือนกัน (1,024 โทเค็นขึ้นไป) ซ้ำ โทเค็นขาเข้าที่ตรงกับแคชต้นทางจะคิดค่าบริการที่ 30% ของราคาขาเข้า ตรวจสอบได้จาก usage.prompt_tokens_details.cached_tokens ในการตอบกลับ และ cachedTokens ของ GET /usage/logs การตรงแคชหรือไม่อาจต่างกันในแต่ละการเรียกตามนโยบายของต้นทาง โมเดล Google ไม่มีแคชจึงใช้ราคาขาเข้าเต็ม โมเดล Claude ก็ไม่ได้ขอแคช จึงใช้ราคาขาเข้าเต็มเช่นกัน
• ยกเว้น REPORT_ONLY_MODEL: ridm/saju-report เป็นแบบครั้งเดียวที่ไม่มีหน่วยความจำ จึงใช้ที่เอนด์พอยต์นี้ไม่ได้ (400)

Custom Profile (โปรไฟล์กำหนดเอง)

เฉพาะโมเดล ridm/* เก็บและจัดการชื่อฟิลด์-ค่าที่กำหนดเองแยกตามผู้ใช้ปลายทาง สามารถเก็บค่าฟิลด์ที่ดึงออกมาอัตโนมัติ ให้พาร์ทเนอร์กำหนดค่าเอง หรือใส่ฟิลด์ที่ต้องการลงในพรอมต์ของเทิร์นนี้ได้ ค่าจะสะสมไปเรื่อยๆ และแม้สคีมาจะเปลี่ยน ค่าเดิมก็ยังคงอยู่ (soft-update)

พารามิเตอร์คำขอ (POST /api/v1/partners/v1/chat/completions)

ตัวอย่างคำขอ (RIDM chat)

{
  "model": "ridm/gpt-5.6-terra",
  "user": "enduser_123",
  "messages": [
    { "role": "user", "content": "Help me plan my kid's birthday party tomorrow" }
  ],
  "extractProfileFields": ["childAge", "interests", "budget", "constraints"],
  "injectProfileFields": ["name", "childAge", "interests"],
  "endUserProfile": {
    "name": "Jane Kim",
    "childAge": "7",
    "interests": "science, art"
  },
  "profileValueMaxChars": 200
}

โปรไฟล์ในการตอบกลับ

การตอบกลับของคำขอที่ส่งพารามิเตอร์โปรไฟล์ (สำหรับสตรีมมิงคือ message_done) จะมีฟิลด์ customProfile แนบมา

"customProfile": {
  "injected": ["name", "childAge", "interests"],  // fields injected into this turn's prompt
  "stored": 4,                                     // number of fields currently stored
  "extractPending": ["budget"]                     // extraction targets that have no value yet
}

API ลบ

หากต้องการลบฟิลด์ที่ระบุ ให้ส่งคำขอ DELETE:

DELETE /api/v1/partners/v1/profile/{endUserId}/field/{key}
X-Partner-Api-Key: your-api-key

การตอบกลับ: { "success": true, "data": { "deleted": true } } — แม้เป็นคีย์ที่ไม่มีอยู่หรือ endUserId ที่ไม่เคยเห็นมาก่อน ก็จะได้ 200 พร้อม "deleted": false (ไม่สร้างผู้ใช้ปลายทางใหม่) API นี้ไม่มีรหัสข้อผิดพลาดเฉพาะ — มีเพียงข้อผิดพลาดทั่วไป

เพดานและข้อจำกัด

• เพดานฟิลด์: สูงสุด 100 ฟิลด์ต่อผู้ใช้ปลายทาง หากเกินจะลบฟิลด์ที่เก่าที่สุดก่อน
• ความยาวค่า: ค่าเริ่มต้น 150 ตัวอักษรต่อฟิลด์ สูงสุด 500 ตัวอักษร ปรับได้ด้วย profileValueMaxChars
• การเก็บแบบสะสม: ค่าที่ดึงด้วย extractProfileFields จะสะสม ค่าที่ว่างหรือเป็น null จะข้ามและคงค่าเดิมไว้ การลบฟิลด์ทำได้เฉพาะผ่าน DELETE API ด้านบน (หรือการลบอัตโนมัติตามลำดับเก่าสุดเมื่อเกิน 100 รายการ) ค่าที่ระบุด้วย endUserProfile จะเขียนทับค่าที่ดึงได้
• เกณฑ์ความยาวค่าเป็นรายคำขอ: profileValueMaxChars ไม่ถูกบันทึก และใช้เฉพาะกับค่าที่เก็บในคำขอนั้น
• Soft Update: แม้สคีมา (ชื่อฟิลด์) จะเปลี่ยน ค่าเดิมก็ยังคงอยู่ และจะรวมกับค่าใหม่ทุกครั้งที่เรียก
• เฉพาะ ridm/*: การขายต่อ (openai/*, google/*) จะละเว้นโปรไฟล์

LLM API (ขายต่อ)

ขายต่อโมเดล LLM ต้นฉบับ เช่น openai/*, google/* (ไม่มีหน่วยความจำ ตอบกลับตามต้นฉบับ) ในคำขอของโมเดลขายต่อ user, systemPrompt, recallCount, memoryCap, summaryEvery, emotion, candor จะถูกละเว้น (คำสั่งระบบให้ใส่เป็น {"role":"system"} ใน messages) และการตอบกลับจะไม่มีฟิลด์หน่วยความจำ (recalledMemories ฯลฯ) ราคา = ต้นทุน × อัตราแลกเปลี่ยน × 1.10

โมเดลที่ให้บริการ (รายการเดียวกับ GET /api/v1/partners/v1/models)

• OpenAI (23 รุ่น): openai/gpt-6-astra · openai/gpt-6-sol · openai/gpt-6-luna · openai/gpt-5.6-sol · openai/gpt-5.6-terra · openai/gpt-5.6-luna · openai/gpt-5.5 · openai/gpt-5.4 · openai/gpt-5.4-mini · openai/gpt-5.4-nano · openai/gpt-5.2 · openai/gpt-5.1 · openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-4.1 · openai/gpt-4.1-mini · openai/gpt-4.1-nano · openai/gpt-4o · openai/gpt-4o-mini · openai/o3 · openai/o3-mini · openai/o4-mini
• Google (3 รุ่น): google/gemini-3.5-flash · google/gemini-3.5-flash-lite · google/gemini-3.1-pro
• Anthropic (13 รุ่น): ดูหัวข้อโมเดล Claude ด้านล่าง
• RIDM: มีโมเดลแบบจดจำที่ใส่คำนำหน้า ridm/ ให้ชื่อเดียวกับแต่ละโมเดลข้างต้น (ราคาขายต่อ × 1.3) และ ridm/saju-report สำหรับรายงานซาจูโดยเฉพาะ (เรียกได้ทาง /reading/report เท่านั้น)

curl https://api.hrum.ai/api/v1/partners/v1/models \
  -H "X-Partner-Api-Key: your-api-key"

การตอบกลับของ GET /api/v1/partners/v1/models — ไม่ใช่รูปแบบ models.list ของ OpenAI ราคาเป็นวอน (₩) ต่อ 1M โทเค็น และตัวเลขด้านล่างเป็นตัวอย่าง โมเดล Claude จะแสดงในรายการเฉพาะเมื่อตั้งค่าไว้ในเซิร์ฟเวอร์

{
  "success": true,
  "data": {
    "models": [
      { "modelId": "openai/gpt-5.6-terra", "upstream": "gpt-5.6-terra", "provider": "openai", "input_cost_krw": 1234, "output_cost_krw": 9876, "category": "base" },
      { "modelId": "ridm/gpt-5.6-terra", "upstream": "gpt-5.6-terra", "provider": "openai", "input_cost_krw": 1604.2, "output_cost_krw": 12838.8, "category": "ridm" }
    ]
  }
}

API นี้ไม่มีรหัสข้อผิดพลาดเฉพาะ — มีเพียงข้อผิดพลาดทั่วไป ใช้ได้ฟรี

โมเดลคิด (ให้เหตุผล) กับ max_tokens: โมเดลที่ใช้การคิดแบบซ่อน (thinking/reasoning) จะนับโทเค็นการคิดรวมในเพดานขาออก เซิร์ฟเวอร์เพิ่มส่วนเผื่อให้แล้ว แต่ถ้า max_tokens เล็กมาก (เช่น 16) เนื้อหาอาจว่างและตอบกลับด้วย finish_reason: "length" และโทเค็นที่ต้นทางใช้ไปจะถูกคิดค่าบริการ ค่าขั้นต่ำที่แนะนำคือ 64 ขึ้นไป โมเดลที่เกี่ยวข้อง: openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-6-astra · openai/o3 · openai/o3-mini · openai/o4-mini · anthropic/claude-opus-5 · anthropic/claude-opus-5-5 · anthropic/claude-fable-5 · anthropic/claude-fable-5-1 · google/gemini-3.1-pro (รวมโมเดลชื่อเดียวกันที่มีคำนำหน้า ridm/)

ส่วนเผื่อสำหรับการคิดกับโทเค็นที่ถูกเรียกเก็บ: โมเดลที่ปิดการคิดไม่ได้ (openai/gpt-5 · openai/gpt-5-mini · openai/gpt-5-nano · openai/gpt-6-astra · openai/o3 · openai/o3-mini · openai/o4-mini · google/gemini-3.1-pro) และโมเดลที่เปิด thinking ไว้เสมอ (anthropic/claude-opus-5 · anthropic/claude-opus-5-5 · anthropic/claude-fable-5 · anthropic/claude-fable-5-1) (รวมโมเดลชื่อเดียวกันที่มีคำนำหน้า ridm/) เซิร์ฟเวอร์จะเพิ่มส่วนเผื่อสำหรับการคิด (สูงสุด 1,500 โทเค็น) บน max_tokens ที่ขอเพื่อรับประกันว่าจะได้คำตอบ โทเค็นการคิดถูกเรียกเก็บในราคาขาออกด้วย โทเค็นขาออกที่ถูกเรียกเก็บจริงจึงอาจมากกว่า max_tokens (ตัวอย่าง: คำขอ max_tokens 200 ถูกเรียกเก็บ การคิด 747 + เนื้อหา 81 = 828 โทเค็น) หากต้องคุมเพดานค่าใช้จ่ายอย่างเข้มงวด ให้ใช้โมเดลที่ปิดการคิดได้ เช่น google/gemini-3.5-flash

POST /api/v1/partners/v1/chat/completions

พารามิเตอร์คำขอ (ไม่มีเลเยอร์หน่วยความจำ)

ตัวอย่างการใช้งาน (เข้ากันได้กับ OpenAI SDK)

const client = new OpenAI({
  apiKey: 'your-float-api-key',
  baseURL: 'https://api.hrum.ai/api/v1/partners/v1',
  defaultHeaders: { 'X-Partner-Api-Key': 'your-float-api-key' }
});

const response = await client.chat.completions.create({
  model: 'openai/gpt-5.6-terra',
  messages: [{ role: 'user', content: 'Hello' }]
});
// RIDM model example: model: 'ridm/gpt-5.6-terra'

การตอบกลับ

การตอบกลับแบบไม่สตรีมใช้สคีมาที่เข้ากันได้กับ OpenAI และเพิ่ม costUsd · costWon · requestId ส่วน stream: true ไม่ใช่รูปแบบ chunk ของ OpenAI จึงอ่านด้วยตัวแยกวิเคราะห์สตรีมของ OpenAI SDK ไม่ได้ — ให้ดูรูปแบบสตรีมมิง (SSE) แล้วแยกวิเคราะห์เอง

{
  "id": "chatcmpl-1791452814000",
  "object": "chat.completion",
  "created": 1791452814,
  "model": "openai/gpt-5.6-terra",
  "usage": { "prompt_tokens": 9, "completion_tokens": 12, "prompt_tokens_details": { "cached_tokens": 0 } },
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help?" }, "finish_reason": "stop" }
  ],
  "costUsd": 0.000162,
  "costWon": 1,
  "requestId": "resale-..."
}

รหัสข้อผิดพลาดเหมือนกับตารางข้อผิดพลาดของ RIDM Memory API โมเดลขายต่อจะมีเพดานการใช้จ่ายรายวัน (RATE_LIMITED) ด้วย

API AI อ่านดวงซาจู

AI แบบสร้างสรรค์ (Generative AI) วิเคราะห์ซาจูและให้การตีความดวงพร้อมคำแนะนำเฉพาะบุคคล คิดค่าบริการตามโทเค็น และคืนเฉพาะผลการตีความ

POST /api/v1/partners/v1/reading

สร้างการอ่านดวงซาจูด้วย AI จากซาจู พรอมต์และทฤษฎีภายในไม่เปิดเผย

พารามิเตอร์คำขอ

พารามิเตอร์คำขอ — ตัวเลือก tools

ตัวอย่างคำขอ

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": "Is this a good year to change jobs?",
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" },
    "maxLength": 600,
    "tone": "warm"
  }'

ตัวอย่างการตอบกลับ

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

ฟิลด์ในการตอบกลับ

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไปแล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

รายการที่รวมอยู่ — จื่อเวยโต่วซู่ · โหราศาสตร์ตะวันตก · ทำนายฝัน · ไพ่ทาโรต์

ใน AI ซาจูมี AI ซาจู · จื่อเวยโต่วซู่ · โหราศาสตร์ตะวันตก · ไพ่ทาโรต์ · ทำนายฝันอยู่ครบ เสาประจำวันจะสะท้อนในทุกการอ่านดวงโดยพื้นฐานแม้ไม่เรียกแยก (ไม่มีค่าบริการเพิ่ม) เมื่อเรียกแบบรวมครั้งเดียว จะอ่านดวงร่วมกันโดยใช้ผลคำนวณของรายการที่รวมอยู่เป็นหลักฐาน และรายการที่ไม่ต้องการให้ตัดออกด้วย exclude หากต้องการเรียก AI เพียงตัวเดียว ให้ใช้ only หากต้องการแค่ผลคำนวณ ก็เรียกรายการเดียวกันแยกทีละตัวทางเอนด์พอยต์แบบคำนวณ (/ziwei-chart · /astrology (โหราศาสตร์ตะวันตกแบบครบชุด) · /dream · /tarot) เพื่อสร้างแอปเองได้ ใน /reading/memory ก็ใช้ฟิลด์เดียวกัน

• การคิดค่าบริการ: นำราคาโทเค็นเดิม (โทเค็นขาเข้าเท่ากับจำนวนตัวอักษรของคำถาม + persona + บล็อกหลักฐานของรายการที่รวม × 0.25 และโทเค็นขาออก) มาบวกราคา 1 ครั้งของเอนด์พอยต์เดี่ยวของแต่ละรายการที่รวมอยู่ บล็อกหลักฐานเป็นสรุปไม่เกิน 1,500 ตัวอักษรต่อรายการ รายการที่ฟีเจอร์ถูกปิดในบัญชีหรือไม่มีราคาจะไม่ถูกรวม ค่าบริการแต่ละรายการและช่วงราคาโดยประมาณต่อ 1 ครั้งอยู่ที่ ราคา
• คำขอที่ส่งเฉพาะสี่เสา (saju) ไม่มีวันเดือนปีเกิด จึงไม่รวมจื่อเวยโต่วซู่ · โหราศาสตร์ตะวันตก (ทำนายฝัน · ไพ่ทาโรต์ยังรวมอยู่)
• ความสัมพันธ์กับ tools.astrology: หากรวมรายการโหราศาสตร์ตะวันตก จะข้ามการแทรกผังของ tools.astrology เพื่อไม่ให้ใส่ผังดวงกำเนิดเดียวกันซ้ำสองครั้ง หากรายการโหราศาสตร์ตะวันตกถูกตัดออก (exclude หรือฟีเจอร์ปิด) tools.astrology จะทำงานเหมือนตอนนี้
• ระบบความปลอดภัยของการทำนายฝัน: หากเนื้อหา dream เป็นการแสดงออกถึงภาวะวิกฤต จะไม่เรียก AI แต่คืนข้อมูลความช่วยเหลือ (support) ด้วย costPoints: 0
• สวิตช์ฟีเจอร์: ตอนนี้เปิดอยู่ หากปิดการตั้งค่าเซิร์ฟเวอร์ แม้ส่ง exclude · dream · tarot ก็จะถูกละเว้น และการอ่านดวง · ราคา · การตอบกลับจะเหมือนสมัยที่ยังไม่มีรายการที่รวมอยู่ (ไม่มี modulesUsed · moduleFees · tarot)

ตัวอย่างคำขอ (POST /api/v1/partners/v1/reading)

{
  "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "female" },
  "question": "I can't stop thinking about last night's dream. What could it mean for me right now?",
  "dream": "큰 뱀이 집 안으로 들어와 내 발 옆에 똬리를 틀었어요",
  "tarot": { "spread": "past-present-future" }
}

ตัวอย่างการตอบกลับ

{
  "success": true,
  "data": {
    "interpretation": "뱀이 집 안으로 들어와 곁에 머무는 꿈은...",
    "sajuSource": "computed",
    "modulesUsed": ["saju", "dream", "ziwei", "astro", "tarot"],
    "moduleFees": { "dream": 30, "ziwei": 50, "astro": 20, "tarot": 20 },
    "tarot": {
      "lang": "ko",
      "count": 3,
      "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
      "reversedAllowed": true,
      "seed": null,
      "cards": [
        { "position": 1, "positionLabel": "과거", "id": "wands_10", "name": "완드의 10", "nameEn": "Ten of Wands", "arcana": "wands", "reversed": true, "keywords": ["내려놓기", "위임", "해방"], "meaning": "무거운 짐을 마침내 내려놓거나 도움을 받기 시작하는 시기.", "imageUrl": "https://console.hrum.ai/tarot/cards/v2/wands_10.webp" }
      ],
      "cardBackUrl": "https://console.hrum.ai/tarot/cards/v2/back.webp"
    },
    "usage": {
      "inputTokens": 3140,
      "outputTokens": 760
    },
    "costPoints": 162
  }
}

เฉพาะซาจู (ตัดรายการอื่นออกทั้งหมด) (POST /api/v1/partners/v1/reading)

{
  "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "female" },
  "question": "Is this a good year to change jobs?",
  "exclude": ["ziwei", "astro"]
}

เรียก AI ตัวเดียวแยก — only

ใน AI ซาจูมี AI ซาจู · จื่อเวยโต่วซู่ · โหราศาสตร์ตะวันตก · ไพ่ทาโรต์ · ทำนายฝันอยู่ครบ แทนที่จะเรียกแบบรวมครั้งเดียวเหมือนข้างบน ก็เรียก AI ที่ต้องการเพียงตัวเดียวแยกด้วย only ได้ AI ตัวนั้นจะตอบโดยดูเฉพาะหลักฐานของตัวเอง (ผังดวง · ผัง · ไพ่ที่สุ่มได้ · ตัวเลือกการทำนายฝัน) และไม่ใส่รายการอื่น

• การคิดค่าบริการ: ราคาโทเค็น (คำถาม + persona + บล็อกหลักฐานของ AI ตัวนั้นเพียงบล็อกเดียว จำนวนตัวอักษร × 0.25 เป็นโทเค็นขาเข้า และโทเค็นขาออก) + ค่าบริการคงที่ของรายการนั้น 1 รายการ ราคาโดยประมาณต่อ 1 ครั้งแยกตามโดเมนอยู่ที่ ราคา
• ใช้ร่วมกับ exclude ไม่ได้: หากส่งทั้งสองจะได้ 400 ONLY_WITH_EXCLUDE หากไม่มีอินพุตที่ AI ตัวนั้นต้องใช้จะได้ 400 ONLY_REQUIRES_INPUT หากฟีเจอร์นั้นปิดในบัญชีจะได้ 400 ONLY_DOMAIN_UNAVAILABLE — จะไม่ตอบแทนด้วยการอ่านซาจู หากเป็นวันที่ที่คำนวณผังดวง · ผังไม่ได้จะได้ 400 ONLY_INPUT_INVALID
• tarot · dream ไม่ต้องใช้วันเดือนปีเกิด ส่งแค่คำถามและไพ่ (หรือเนื้อหาความฝัน) โดยไม่ต้องมี birth · saju ก็ได้ only ที่ไม่ใช่ saju ไม่ใช้ซาจู การตอบกลับจึงไม่มี sajuSource
• สวิตช์ฟีเจอร์: ใช้การตั้งค่าเซิร์ฟเวอร์เดียวกับรายการที่รวมอยู่และตอนนี้เปิดอยู่ หากปิดการตั้งค่า only จะถูกละเว้นและทำงานเหมือนการอ่านดวงซาจูเดิม

ตัวอย่างคำขอ — เฉพาะ AI ไพ่ทาโรต์ (POST /api/v1/partners/v1/reading)

{
  "question": "Should I keep pushing ahead with the job change I'm preparing?",
  "only": "tarot",
  "tarot": { "spread": "past-present-future" }
}

ตัวอย่างการตอบกลับ

{
  "success": true,
  "data": {
    "interpretation": "과거 자리의 완드의 10 역방향은 오래 짊어진 짐을...",
    "only": "tarot",
    "modulesUsed": ["tarot"],
    "moduleFees": { "tarot": 20 },
    "tarot": {
      "lang": "ko",
      "count": 3,
      "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
      "reversedAllowed": true,
      "seed": null,
      "cards": [
        { "position": 1, "positionLabel": "과거", "id": "wands_10", "name": "완드의 10", "nameEn": "Ten of Wands", "arcana": "wands", "reversed": true, "keywords": ["내려놓기", "위임", "해방"], "meaning": "무거운 짐을 마침내 내려놓거나 도움을 받기 시작하는 시기.", "imageUrl": "https://console.hrum.ai/tarot/cards/v2/wands_10.webp" }
      ],
      "cardBackUrl": "https://console.hrum.ai/tarot/cards/v2/back.webp"
    },
    "usage": {
      "inputTokens": 1180,
      "outputTokens": 720
    },
    "costPoints": 37
  }
}

ข้อควรระวัง

• คืนเฉพาะผลการตีความ: การตอบกลับมีเพียงข้อความการตีความดวงที่สร้างขึ้น ไม่เปิดเผยพรอมต์ภายในหรือทฤษฎีซาจู
• candorApplied: เฉพาะเมื่อส่ง candor เป็น t การตอบกลับจะมีโทนคำพูดที่ใช้จริง (t | f) แนบมา /reading/memory ก็เหมือนกัน (โทนคำพูด (ชื่อชั่วคราว))
• เกณฑ์การคิดค่าบริการ: ขาเข้า = (จำนวนตัวอักษร question + persona) × 0.25 โทเค็น (+ จำนวนตัวอักษรคำบรรยาย YouTube ที่แทรกใน /reading × 0.25) ขาออก = โทเค็น completion จริง การแทรกซาจู · พรอมต์ระบบไม่คิดค่าบริการ และ usage.inputTokens มีไว้เพื่ออ้างอิง หากเปิดรายการที่รวมอยู่ (ดวงวันนี้ · จื่อเวยโต่วซู่ · โหราศาสตร์ตะวันตก · ทำนายฝัน · ไพ่ทาโรต์) จะบวกบล็อกหลักฐานนั้นและค่าบริการคงที่ต่อรายการ costPoints คือยอดที่หักจริง
• ภาษาของการตอบกลับ: คำถามที่ไม่ใช่ภาษาเกาหลีจะตอบเป็นภาษาเดียวกับคำถาม
• ไม่ทราบเวลาเกิด: หากละ hour จะตัดเสายามออกและตีความจาก 3 เสา ปี · เดือน · วัน

API AI อ่านดวงซาจู · หน่วยความจำ

โฮสต์ความจำการสนทนาแยกตามผู้ใช้ปลายทาง และอ่านดวงต่อจากบริบทในอดีตเมื่อกลับมาใช้อีกครั้ง มอบประสบการณ์การปรึกษาต่อเนื่องแบบเฉพาะบุคคล ราคาเป็น 1.3 เท่าของราคาโทเค็นของ AI อ่านดวงซาจู (ต่อ 1M โทเค็น ขาเข้า 3,754 วอน · ขาออก 30,030 วอน — การอ่านดวงคือขาเข้า 2,888 วอน · ขาออก 23,100 วอน ไม่รวม VAT)

POST /api/v1/partners/v1/reading/memory

สร้างการอ่านดวงซาจูด้วย AI จากความจำของผู้ใช้ปลายทางแต่ละคน

พารามิเตอร์คำขอ

พารามิเตอร์คำขอ — ตัวเลือก tools

ตัวอย่างการตอบกลับ

{
  "success": true,
  "data": {
    "interpretation": "당신의 사주에서 보이는 특징은...",
    "sajuSource": "computed",
    "memory": {
      "used": true,
      "summaryInjected": false,
      "notesInjected": 2,
      "tags": ["직장"],
      "overheadTokens": 120
    },
    "usage": {
      "inputTokens": 750,
      "outputTokens": 380
    },
    "costPoints": 36,
    "toolsUsed": ["memory"]
  }
}

ฟิลด์การตอบกลับอื่นๆ (sajuMismatch, toolsSkipped, filesUsed) เหมือนกับ API AI อ่านดวงซาจู เอกสารที่ระลึกอัตโนมัติจะอยู่ใน filesRecalled และถ้า tools.emotion: true จะมี emotion แนบมา เกณฑ์การคิดค่าบริการ (ยกเว้น YouTube) ก็เหมือนกับ API การอ่านดวง

ตัวอย่างคำขอ

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": "About the job change we talked about last time: is next month a good time to make the move?",
    "birth": { "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female" }
  }'

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

API จัดการหน่วยความจำ

AI อ่านดวงซาจูแบบหน่วยความจำ (POST /reading/memory) และแชต RIDM (user ของโมเดล ridm/*) ใช้คลังความจำของผู้ใช้ปลายทางเดียวกัน {endUserId} ในเส้นทางด้านล่างคือค่าที่ส่งไปในตอนนั้นตามเดิม (เช่น หากแบ่งแชตเป็นรายเซสชัน ก็คือคีย์ทั้งหมดอย่าง memberId:chatId)

ตัวอย่างคำขอ · การตอบกลับ

# Get stored memory
curl https://api.hrum.ai/api/v1/partners/v1/memory/member-1024 \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "summary": "이직을 고민 중이며 다음 달 면접을 앞두고 있다...",
    "metaSummary": "...",
    "tags": ["이직", "면접"],
    "profile": null,
    "concerns": ["..."],
    "facts": []
  }
}

# Message list (oldest first)
curl "https://api.hrum.ai/api/v1/partners/v1/memory/member-1024/messages?limit=2&offset=0" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "messages": [
      { "id": "...", "role": "user", "content": "이직 고민이 있어요", "tags": ["이직"], "createdAt": "2026-10-11T09:00:00.000Z" },
      { "id": "...", "role": "assistant", "content": "...", "tags": [], "createdAt": "2026-10-11T09:00:04.000Z" }
    ],
    "offset": 0,
    "limit": 2,
    "total": 18
  }
}

# Tag search (tags as stored: 이직 = job change, 면접 = interview)
curl "https://api.hrum.ai/api/v1/partners/v1/memory/search?endUserId=member-1024&tags=이직,면접" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "query": { "tags": ["이직", "면접"] },
    "results": [
      { "id": "...", "summary": "다음 달 면접 일정을 이야기함", "level": 0, "tags": ["면접"], "createdAt": "2026-10-11T09:00:00.000Z" }
    ]
  }
}

# Save a conversation (no AI generation)
curl -X POST https://api.hrum.ai/api/v1/partners/v1/memory/member-1024/turns \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "I'\''m worried about my interview next month" },
      { "role": "assistant", "content": "You'\''ve prepared well. You'\''ll do fine." }
    ],
    "summary": "Call about feeling anxious before next month'\''s interview",
    "tags": ["interview"]
  }'

{
  "success": true,
  "data": {
    "endUserId": "member-1024",
    "saved": 2,
    "summarySaved": true
  }
}

# Delete everything (memory + uploaded files) — 204, no body
curl -X DELETE https://api.hrum.ai/api/v1/partners/v1/memory/member-1024 \
  -H "X-Partner-Api-Key: your-api-key"

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

ข้อควรระวัง

• ราคา 1.3 เท่า: เนื่องจากการโฮสต์หน่วยความจำ ราคาโทเค็นขาเข้า/ขาออกจึงเป็น 1.3 เท่าของ AI อ่านดวงซาจู (ต่อ 1M โทเค็น ขาเข้า 3,754 วอน · ขาออก 30,030 วอน ไม่รวม VAT)
• ต้องมี endUserId: ผู้ใช้ปลายทางแต่ละคนต้องมี ID ที่ไม่ซ้ำกัน และเมื่อเรียกด้วย ID เดียวกัน บริบทในอดีตจะถูกคงไว้
• การเก็บรักษาหน่วยความจำ: หน่วยความจำที่เก็บไว้จะถูกเก็บรักษาจนกว่าจะลบอย่างชัดแจ้ง

API รายงานซาจู

ไม่ต้องถาม แค่กดปุ่มครั้งเดียวก็ได้การตีความซาจูทั้งหมดในครั้งเดียว ตั้งแต่ภาพรวม · การเงิน · ความรัก · วัยจร 10 ปี เป็นสินค้าแบบชำระเงินรายชิ้นที่แยกจากแบบสนทนา (reading) ค่าเริ่มต้นคือโมเดลเฉพาะ ridm/saju-report (โมเดลเฉพาะทางด้านรายงานของ RIDM เอง — ด้วยลักษณะของสินค้าแบบครั้งเดียวจึงไม่มีหน่วยความจำ) เพดานการตอบของ API การอ่านดวงคือ 2,000 ตัวอักษร — หากต้องการคำอธิบายยาวกว่านั้น (สูงสุด 12 หัวข้อ ประมาณ 6,000 ตัวอักษร) ให้ใช้ API รายงานนี้

POST /api/v1/partners/v1/reading/report

ใส่วันเดือนปีเกิด (หรือซาจู) แล้วจะคืนรายงานซาจูแบบ Markdown แยกตามหัวข้อ

พารามิเตอร์คำขอ

รายงานเขียนเป็นภาษาเกาหลีเสมอ หากส่งฟิลด์ที่ไม่มีในตารางข้างบน เช่น speed · tools · lang · question จะถูกปฏิเสธด้วย 400

ตัวอย่างคำขอ

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": ["총평", "재물운", "연애·인연"]
  }'

การตอบกลับ

{
  "success": true,
  "data": {
    "report": "## 총평\n...",        // full Markdown, section by section
    "sections": ["총평", "..."],
    "sajuSource": "computed",
    "usage": { "inputTokens": 5756, "outputTokens": 2019 },
    "costPoints": 77,
    "model": "ridm/saju-report"
    // "candorApplied": "t"  — only when candor was sent as t (t | f)
  }
}

• แทรกซาจูฟรี: การคำนวณ · แทรกปฏิทินหมื่นปีและพรอมต์ระบบไม่คิดค่าบริการ ขาเข้าคิดเฉพาะความยาว persona ขาออกคิดตามโทเค็นที่ใช้จริง
• ค่าใช้จ่ายที่วัดจริง: รายงานค่าเริ่มต้น 8 หัวข้อ (ประมาณ 3,000 ตัวอักษร) 1 ครั้งประมาณ 85P (ตามขาออก ₩38,077/1M)
• การลองใหม่จะคิดค่าบริการอีกครั้ง หากต้องการนำผลของอินพุตเดิมกลับมาใช้หลังได้รับการตอบกลับ ให้เก็บไว้ฝั่งไคลเอนต์ (Idempotency)

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

API สรุป YouTube

ดึงคำบรรยายของวิดีโอ YouTube แล้วให้บริการสรุปและวิเคราะห์ถาม-ตอบ (Q&A) หากไม่มีคำบรรยายจะได้ข้อผิดพลาด 400 (ไม่คิดค่าบริการ)

POST /api/v1/partners/v1/youtube/summary

พารามิเตอร์คำขอ

ตัวอย่างคำขอ

curl -X POST https://api.hrum.ai/api/v1/partners/v1/youtube/summary \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "maxLength": 1000 }'

ตัวอย่างการตอบกลับ

{
  "success": true,
  "data": {
    "summary": "## 0:00~1:30 오프닝\n영상 제목 설명...\n\n## 1:30~5:00 본론\n...",
    "video": {
      "videoId": "dQw4w9WgXcQ",
      "title": "Video Title",
      "channel": "Channel Name"
    },
    "transcriptSource": "supadata",
    "usage": {
      "promptTokens": 7059,
      "completionTokens": 1384
    },
    "costPoints": 51,
    "model": "ridm/gpt-5.6-terra"
  }
}

ข้อควรระวัง

• ต้องมีคำบรรยาย: หากไม่มีคำบรรยายจะได้ TRANSCRIPT_UNAVAILABLE 400 (ไม่คิดค่าบริการ)
• ข้อผิดพลาด: URL · ID ไม่ถูกต้อง 400 INVALID_YOUTUBE_URL / สร้างสรุปล้มเหลว 400 LLM_GENERATION_FAILED / ยอดคงเหลือไม่พอ 402 INSUFFICIENT_BALANCE
• การคิดค่าบริการ: คิดตามโทเค็น ใช้ราคาขายต่อตามเดิม (ต้นทุน × 1.1) ของโมเดลที่ใช้ (ค่าเริ่มต้น ridm/gpt-5.6-terra) — ไม่มีเลเยอร์หน่วยความจำ จึงไม่ใช้ราคา RIDM Memory (× 1.3) costPoints = ปัดขึ้น (โทเค็นขาเข้า × ราคาขาเข้า + โทเค็นขาออก × ราคาขาออก) ราคาคิดต่อ 1M โทเค็น (ไม่รวม VAT)
• ค่าใช้จ่ายที่วัดจริง: วิดีโอ 20~30 นาที 1 ครั้งประมาณ 60P (รวมโทเค็น)
• เชื่อมกับการอ่านดวง: ใน API AI อ่านดวงซาจู (/reading) แทรกคำบรรยายของลิงก์ในคำถามได้ด้วย tools: { "youtube": true } (ฟิลด์ youtube ระดับบนสุดจะถูกละเว้น) การแทรก YouTube รองรับเฉพาะใน /reading (/reading/memory ยังไม่รองรับ) หากส่งไปที่ /reading/memory จะไม่ดึงคำบรรยาย และแจ้งใน toolsSkipped เป็น {"tool": "youtube", "reason": "unavailable"}

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

เปิด-ปิดฟีเจอร์

API สรุป YouTube เลือกเปิดใช้ (opt-in) ได้ทั้งระดับบัญชีพาร์ทเนอร์และระดับคำขอ จัดการสถานะเปิดใช้งานทั้งระบบได้ที่ "ตั้งค่าฟีเจอร์" ในคอนโซล และเปิดใช้รายคำขอโดยระบุ youtube:true ระดับบนสุดสำหรับ chat และ tools: { "youtube": true } สำหรับ reading

• ปิดทั้งระบบ: ตอบกลับ 403 { code: 'FEATURE_DISABLED', feature: 'youtube' }
• ระดับคำขอ: ไม่ระบุ youtube:true หรือเป็น false = ไม่แทรก YouTube

API ประมวลผลเอกสาร

อัปโหลดเอกสาร PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), CSV, ข้อความ, Markdown, ฮันกึล (.hwpx) แล้ววิเคราะห์ด้วย AI เพื่อนำเข้าสู่ฐานความรู้ตามบริบทได้ เอกสารจะถูกดึงข้อความอัตโนมัติ และหากเปิดตัวเลือก "วิเคราะห์ด้วย AI" จะแบ่งเอกสารเป็นช่วงตามบริบท แล้วสร้างสรุปและแท็กค้นหาของแต่ละช่วงเก็บไว้

รูปแบบที่รองรับและข้อจำกัด

เอนด์พอยต์

อัปโหลดไฟล์

POST /api/v1/partners/v1/files

อัปโหลดไฟล์ในรูปแบบ Multipart form

ฟิลด์คำขอ

ตัวอย่าง cURL

curl -X POST https://api.hrum.ai/api/v1/partners/v1/files \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "endUserId=user_123" \
  -F "analyze=true"

ตัวอย่างการตอบกลับ

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "sample.pdf",
    "originalName": "sample.pdf",
    "mime": "application/pdf",
    "size": 125000,
    "textLength": 8942,
    "charsCapped": false,
    "textPreview": "1장. 개요 ...",
    "summary": "문서 전체 요약...",
    "context": "문서 전체 요약...",
    "status": "analyzed",
    "analysisStatus": "analyzed",
    "analyzeRequested": true,
    "endUserId": "user_123",
    "usage": { "inputTokens": 3100, "outputTokens": 420, "costWon": 1 },
    "totalChunks": 3,
    "createdAt": "2026-08-26T12:34:56Z"
  }
}

รายการ · รายละเอียด · ลบ

# List — newest first, limit 1–100 (default 20)
curl "https://api.hrum.ai/api/v1/partners/v1/files?endUserId=user_123&limit=20&offset=0" \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "files": [ { "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "sample.pdf", "status": "analyzed", ... } ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

# Details — upload response fields + extractedText + chunks
curl https://api.hrum.ai/api/v1/partners/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "name": "sample.pdf",
    ...,
    "extractedText": "1장. 개요 ...",
    "chunks": [
      { "id": "...", "chunkIndex": 0, "context": "1장 요약...", "tags": ["개요"], "textLength": 2980 }
    ]
  }
}

# Delete
curl -X DELETE https://api.hrum.ai/api/v1/partners/v1/files/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

{ "success": true, "data": { "deleted": true } }

การเชื่อมกับ Chat และการอ่านดวง

แนบแบบระบุชัด: เมื่อขอ Chat completions หรือการอ่านดวงด้วย AI สามารถแทรกเอกสารได้สูงสุด 5 รายการด้วยพารามิเตอร์ fileIds ไฟล์ที่วิเคราะห์แล้วจะแทรกสรุปเอกสาร (สูงสุด 500 ตัวอักษร) และข้อความต้นฉบับ ส่วนไฟล์ที่ยังไม่วิเคราะห์จะแทรกข้อความต้นฉบับ (ต้นฉบับจำกัด 40,000 ตัวอักษรต่อไฟล์ / รวม 80,000 ตัวอักษร ไม่แทรกชิ้นย่อย) เอกสารที่แทรกจะถูกเพิ่มต่อท้ายข้อความผู้ใช้ล่าสุดและรวมอยู่ในโทเค็นขาเข้า โมเดลขายต่อรองรับเฉพาะการแทรก fileIds แบบระบุชัด

ระลึกอัตโนมัติ (เฉพาะ ridm/*): ในโมเดล ridm/* chat และ reading-memory จะค้นหาไฟล์ที่วิเคราะห์แล้วซึ่งมีแท็กตรงกับคำถามผู้ใช้แล้วแทรกให้อัตโนมัติ (เฉพาะเมื่อไม่ได้ระบุ fileIds) การตอบกลับจะแสดง ID ไฟล์ที่ระลึกได้ในอาร์เรย์ filesRecalled

ตัวอย่างคำขอ Chat

{
  "model": "ridm/gpt-5.6-terra",
  "messages": [
    { "role": "user", "content": "Can you summarize the main points of this document?" }
  ],
  "fileIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"],
  "user": "user_123"
}

ตัวอย่างการตอบกลับ

{
  "id": "chatcmpl-abc123",
  "choices": [{
    "message": { "content": "문서의 주요 내용은..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 2500, "completion_tokens": 150 },
  "filesUsed": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"]
}

filesRecalled จะแนบมาเฉพาะเมื่อมีไฟล์ที่ระลึกอัตโนมัติ (หากว่างจะละไว้)

ราคาและการคิดค่าบริการ

• อัปโหลดและดึงข้อความ: ฟรี (ไม่คิดค่าโทเค็นการดึงข้อความ)
• วิเคราะห์ด้วย AI (analyze=true): คิดค่าบริการตามโทเค็นที่ใช้จริงในการตรวจหาขอบเขต + สรุปแต่ละช่วง + สรุปทั้งหมด ในราคาของโมเดลวิเคราะห์ แบบซิงโครนัส ≤30,000 ตัวอักษร แบบอะซิงโครนัส >30,000 ตัวอักษร (status: analyzing)
• การแทรกใน Chat: ข้อความเอกสารนับเป็นโทเค็นขาเข้าและคิดค่าบริการเหมือนคำขอ chat ทั่วไป
• บันทึก: ตรวจสอบได้ในบันทึกการใช้งานของคอนโซลตามหมวด file_upload (ฟรี), file_analyze (มีค่าใช้จ่าย ตามโทเค็นที่ใช้จริง)

เปิด-ปิดฟีเจอร์

ฟีเจอร์ประมวลผลเอกสารเปิด/ปิดได้ที่ระดับบัญชีพาร์ทเนอร์ จัดการได้ที่ "ตั้งค่าฟีเจอร์" ในคอนโซล เมื่อปิด คำขอไฟล์ทั้งหมดจะได้การตอบกลับ 403

• ปิดทั้งระบบ: ตอบกลับ 403 { code: 'FEATURE_DISABLED', feature: 'files' }
• ระดับคำขอ: ไม่ระบุ fileIds = ไม่แทรกเอกสาร (ประมวลผลตามปกติ)

สถานะการวิเคราะห์และชิ้นข้อมูล

การตอบกลับของ GET /api/v1/partners/v1/files/:id มี analysisStatus, extractedText, chunks chunks เป็นอาร์เรย์ (แต่ละชิ้น: chunkIndex, context (สรุป), tags สูงสุด 10 รายการ) เฉพาะเมื่อวิเคราะห์เสร็จและ totalChunks มีค่า 2 ขึ้นไป นอกนั้นเป็น null การตอบกลับของการอัปโหลดไม่มี chunks

ข้อควรระวัง

• ตรวจสอบรูปแบบ: รูปแบบที่ไม่รองรับจะคืน 400 { code: 'INVALID_FILE_TYPE' }
• ข้อผิดพลาดอื่นๆ: ไม่มีไฟล์ 400 FILE_NOT_PROVIDED / เกิน 10MB 400 FILE_TOO_LARGE / ไฟล์ไม่มีอยู่ 404 FILE_NOT_FOUND / หาก :id ไม่ใช่ UUID จะได้ 400
• จำเป็นสำหรับการวิเคราะห์: เมื่อ analyze=true หากไม่มี endUserId จะคืน 400 { code: 'END_USER_REQUIRED' }
• ดึงข้อความล้มเหลว: หากเกิดข้อผิดพลาดระหว่างดึงข้อความจากเอกสาร จะคืน 422 { code: 'EXTRACTION_FAILED' }
• ตรวจยอดคงเหลือ: ตรวจว่าเครดิตของพาร์ทเนอร์เพียงพอก่อนขอวิเคราะห์ หากไม่พอจะคืน 402
• นำเข้าฐานความรู้อัตโนมัติ: เมื่อ analyze=true สรุปและแท็กของแต่ละช่วงจะถูกเก็บลงฐานความรู้อัตโนมัติ และเป็นเป้าหมายของ auto-recall ในภายหลัง หากระบุ endUserId จะเพิ่มลงในชั้นความจำของผู้ใช้นั้นด้วย
• อัปโหลดซ้ำ = ไฟล์ใหม่: ทุกครั้งที่อัปโหลดจะสร้างไฟล์ใหม่ (id ใหม่) และถ้า analyze=true จะวิเคราะห์และคิดค่าบริการอีกครั้ง เอกสารเดิมให้อัปโหลดครั้งเดียวแล้วนำ id ที่ได้มาใช้ซ้ำเป็น fileIds

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

วิเคราะห์สภาวะอารมณ์ (Emotion)

วิเคราะห์สภาวะอารมณ์ของผู้ใช้และ AI โดยอาศัยรอบการสรุปใน Chat API ไม่มีการเรียก LLM แยก และเพิ่มเพียงบล็อกวิเคราะห์อารมณ์ลงในพรอมต์สรุป จึงไม่มีค่าบริการเพิ่ม รองรับเฉพาะโมเดล ridm/*

ภาพรวม

เงื่อนไขการเปิดใช้งาน:

1. ทั้งระบบ: partner_emotion_enabled ✓
2. Partner: เปิด "วิเคราะห์สภาวะอารมณ์" ในการตั้งค่าฟีเจอร์ของคอนโซล
3. Request: ระบุ emotion: true
4. Model: รองรับเฉพาะตระกูล ridm/*

รอบการสรุป (summaryEvery)

การวิเคราะห์อารมณ์จะทำงานอัตโนมัติทุกรอบการสรุป ปรับรอบได้ด้วยพารามิเตอร์ summaryEvery (ค่าเริ่มต้น: 5 ช่วง: 1–20)

• summaryEvery=1: อัปเดตอารมณ์เกือบทุกเทิร์น (การสรุปทำงานแบบอะซิงโครนัสหลังตอบกลับ)
• summaryEvery=5: รอบละ 5 เทิร์น (แนะนำ)
• summaryEvery=20: รอบละ 20 เทิร์น (อัปเดตน้อยที่สุด)
• รอบการสรุป · อารมณ์ไม่คิดค่าบริการกับพาร์ทเนอร์ ไม่ว่ารอบจะเป็นเท่าใด

พารามิเตอร์คำขอ

ตัวอย่างคำขอ

{
  "model": "ridm/gpt-5.6-terra",
  "user": "user_123",
  "messages": [
    { "role": "user", "content": "Today was a rough day..." }
  ],
  "emotion": true,
  "summaryEvery": 3
}

ฟิลด์ในการตอบกลับ

ตัวอย่างการตอบกลับ

{
  "id": "chatcmpl-xyz",
  "choices": [{
    "message": { "content": "오늘 하루가 힘들었군요..." },
    "finish_reason": "stop"
  }],
  "emotion": {
    "user": {
      "type10": "sad",
      "tone": "warm",
      "distribution6": {"joy": 100, "sadness": 600, "anger": 50, "fear": 100, "disgust": 50, "surprise": 0}
    },
    "assistant": {
      "distribution6": {"joy": 200, "sadness": 100, "anger": 0, "fear": 0, "disgust": 0, "surprise": 0}
    },
    "trend": "stable",
    "updatedAt": "2026-08-26T12:34:56Z",
    "turnsSinceUpdate": 0
  },
  "usage": {...}
}

คำอธิบายฟิลด์การกระจาย (distribution6)

การตัดสินแนวโน้ม (trend)

• improving: อารมณ์ที่ไม่ใช่เชิงบวก (sadness+anger+fear+disgust) ลดลง 50 ขึ้นไป
• stable: เปลี่ยนแปลงน้อยกว่า 50
• declining: อารมณ์ที่ไม่ใช่เชิงบวกเพิ่มขึ้น 50 ขึ้นไป
• null: ไม่มีข้อมูลของรอบก่อนหน้า

ตัวอย่างการตอบกลับแบบสตรีมมิง (SSE)

ในโหมดสตรีมมิง (stream: true) สภาวะอารมณ์จะรวมอยู่ในข้อมูลของอีเวนต์ SSE event: message_done

event: message_done
data: {"finish_reason":"stop","usage":{...},"costWon":2,"recalledMemories":[],"memorySaved":{"id":"turn-1756200000000","keywords":[]},"emotion":{"user":{"type10":"concerned","tone":"warm","distribution6":{...}},"assistant":{...},"trend":"stable","updatedAt":"2026-08-26T12:34:56Z","turnsSinceUpdate":0}}

data: [DONE]

ข้อมูลค่าใช้จ่าย

• ไม่มีค่าบริการแยก: การวิเคราะห์อารมณ์ทำงานโดยรวมอยู่ในพรอมต์ของรอบการสรุป และโทเค็นของรอบสรุป · อารมณ์ไม่คิดค่าบริการกับพาร์ทเนอร์ คิดค่าบริการเฉพาะโทเค็นขาเข้า · ขาออกของเทิร์นแชตเท่านั้น

ข้อควรระวัง

• ก่อนรอบแรก: ก่อนรอบการสรุปแรกทำงาน จะไม่มีฟิลด์ emotion (เป็นการทำงานปกติ)
• ฟีเจอร์ปิด: หากเป็นคำขอ emotion: true แต่การตั้งค่าฟีเจอร์ทั้งระบบหรือของพาร์ทเนอร์ปิดอยู่ จะตอบกลับ 403 { code: 'FEATURE_DISABLED', feature: 'emotion' } (เหมือน YouTube · การประมวลผลเอกสาร) หากไม่ส่ง emotion หรือเป็น false จะละเฉพาะฟิลด์
• รองรับเฉพาะโมเดล ridm/* หากบัญชีเปิดฟีเจอร์อารมณ์ ฟิลด์ emotion ของคำขอขายต่อ (openai/* · google/*) จะถูกละเว้น หากบัญชีปิดไว้ emotion:true จะได้ 403 FEATURE_DISABLED ไม่ว่าจะเป็นโมเดลใด
• สตรีมมิง: ในการตอบกลับแบบสตรีม emotion จะรวมอยู่ในอีเวนต์ SSE message_done

API รูปภาพซาจู

สร้างงานศิลป์ AI ที่แสดงธาตุทั้งห้าและพลังงานของซาจู คืนค่าเป็นรูปแบบ PNG เข้ารหัส base64 คิดค่าบริการคงที่ ₩200

POST /api/v1/partners/v1/image

สร้างรูปภาพธาตุทั้งห้าของซาจูจากวันเดือนปีเกิด

พารามิเตอร์คำขอ

ตัวอย่างคำขอ

curl -X POST https://api.hrum.ai/api/v1/partners/v1/image \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30, "gender": "female", "style": "portrait" }'

ตัวอย่างการตอบกลับ

{
  "success": true,
  "data": {
    "imageDataUri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
    "costPoints": 200
  }
}

ข้อควรระวัง

• ราคาคงที่: การสร้างรูปภาพทุกครั้งคิดค่าบริการ ₩200
• เวลาในการสร้าง: การสร้างรูปภาพใช้เวลา 20~30 วินาที ตั้งค่าไทม์เอาต์ให้เพียงพอ
• การเข้ารหัส Base64: imageDataUri ที่คืนมาเป็นรูปภาพ PNG ที่เข้ารหัส base64 ใช้กับแท็ก HTML <img src="{imageDataUri}"> ได้โดยตรง
• สไตล์: background (ภาพพื้นหลัง) · icon (ไอคอนแบบมินิมอล) · portrait (ภาพประกอบบุคคล) เปลี่ยนเฉพาะบรรยากาศ ทุกสไตล์มีขนาดเท่ากัน (ค่าเริ่มต้นสี่เหลี่ยมจัตุรัส 1024×1024)
• ไทม์เอาต์: หากต้นทางไม่คืนรูปภาพภายใน 80 วินาที จะคืน 504 IMAGE_UPSTREAM_TIMEOUT และไม่คิดค่าบริการ ลองใหม่อีกครั้ง
• ไม่ทราบเวลาเกิด: หากละ hour จะตัดเสายามออกและตีความจาก 3 เสา ปี · เดือน · วัน

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

API สร้างรูปภาพ (ขายต่อโมเดล)

POST /api/v1/partners/v1/images/generations

เรียกโมเดล GPT-Image · Nano Banana ด้วยคีย์เดียวในรูปแบบเดียวกับ OpenAI Images API ราคาต่อรูปกำหนดไว้ตามโมเดล · ความละเอียด · คุณภาพ และจะหักตามจำนวนเงินในตารางตามเดิม (จำนวนรูปที่สร้าง × ราคาต่อรูป) ค่าโทเค็นขาเข้าของพรอมต์รวมอยู่ในราคาต่อรูปแล้ว ไม่คิดเพิ่มแยก

พารามิเตอร์คำขอ

หากส่ง aspect_ratio · resolution ให้ GPT-Image หรือขอความละเอียดที่โมเดลไม่รองรับ จะถูกปฏิเสธด้วย 400 INVALID_PARAMETER และไม่คิดค่าบริการ

ข้อผิดพลาดอื่นๆ: MODEL_NOT_FOUND · INVALID_MODEL (400 โมเดลไม่มีอยู่), INVALID_PROMPT (400 ต้นทางปฏิเสธพรอมต์), UPSTREAM_ERROR, RATE_LIMITED (ปัจจุบัน HTTP 400 เนื้อหา status 429), INSUFFICIENT_BALANCE (402)

ราคาต่อรูป (₩ ไม่รวม VAT)

ตัวอย่างคำขอ

curl -X POST https://api.hrum.ai/api/v1/partners/v1/images/generations \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/nano-banana-pro",
    "prompt": "A serene mountain landscape at sunset",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }'

ตัวอย่างการตอบกลับ

{
  "created": 1791452814,
  "data": [ { "b64_json": "iVBORw0KGgo..." } ],
  "costWon": 225,
  "requestId": "..."
}

• GPT-Image · โมเดล Google โดยตรงคืนรูปภาพเป็น b64_json ส่วนโมเดล FAL คืนเป็น url
• costWon = ราคาต่อรูป × จำนวนรูปที่สร้างจริง หากต้นทางไม่คืนรูปภาพเลยจะไม่คิดค่าบริการ
• usage (จำนวนโทเค็น) ในการตอบกลับของ GPT-Image มีไว้เพื่ออ้างอิง ไม่ใช้ในการคิดราคา

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

การตอบกลับข้อผิดพลาดใช้รูปแบบ {"success": false, ...} เหมือน API อื่น (เฉพาะการตอบกลับที่สำเร็จที่ไม่ถูกห่อ)

การสร้างที่ใช้เวลานาน — การตอบกลับแบบอะซิงโครนัส (202 ไม่บังคับ)

คำขอความละเอียดสูง · หลายรูปอาจใช้เวลาเกิน 1 นาที หากใส่ Prefer: respond-async ในเฮดเดอร์คำขอ เมื่อผลลัพธ์ไม่พร้อมภายใน 60 วินาที ระบบจะไม่ค้างการเชื่อมต่อไว้ แต่คืน 202 Accepted พร้อม ID งาน และการสร้างจะดำเนินต่อบนเซิร์ฟเวอร์ได้สูงสุด 240 วินาที หากเสร็จภายใน 60 วินาทีจะได้การตอบกลับ 200 เหมือนเดิมทุกอย่าง หากไม่ส่งเฮดเดอร์จะเหมือนเดิมทุกประการ (หากไม่เสร็จภายใน 80 วินาทีจะได้ 504 IMAGE_UPSTREAM_TIMEOUT ไม่คิดค่าบริการ) — ส่งเฮดเดอร์เฉพาะไคลเอนต์ที่พร้อมจัดการ 202

curl -X POST https://api.hrum.ai/api/v1/partners/v1/images/generations \
  -H "X-Partner-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"model": "google/nano-banana-pro", "prompt": "...", "resolution": "4K"}'

HTTP/1.1 202 Accepted
Location: /api/v1/partners/v1/jobs/imgjob_3f2a...
Retry-After: 5
Preference-Applied: respond-async

{
  "id": "imgjob_3f2a...",
  "object": "image.job",
  "status": "pending",
  "pollUrl": "/api/v1/partners/v1/jobs/imgjob_3f2a...",
  "retryAfter": 5,
  "createdAt": "2026-10-12T03:00:00.000Z",
  "expiresAt": "2026-10-13T03:00:00.000Z"
}

GET /api/v1/partners/v1/jobs/{id}

ดึงข้อมูลด้วยคีย์ API เดียวกัน (X-Partner-Api-Key) ทุก Retry-After วินาที การดึงข้อมูลฟรีและไม่นับในโควตาคำขอรายวัน แต่จำกัด 1 ครั้งต่อ 2 วินาทีต่อคีย์ API หากเรียกถี่กว่านั้นจะได้ 429 IMAGE_JOB_POLL_RATE_LIMITED พร้อม Retry-After (วินาที) การตอบกลับเป็น HTTP 200 และแยกสถานะด้วย status ในเนื้อหา

• การคิดค่าบริการ: หักเพียงครั้งเดียวเมื่อผลลัพธ์พร้อม ระหว่างรอจะจองยอดคงเหลือไว้เท่ากับยอดที่คาดไว้ หากล้มเหลว · หมดเวลา การจองจะถูกปลดและไม่คิดค่าบริการ ดึงข้อมูลหลายครั้งก็ไม่คิดค่าบริการซ้ำ
• การเก็บรักษา: ผลลัพธ์ · ข้อผิดพลาดดึงข้อมูลได้ภายใน 24 ชั่วโมงหลังสร้างงาน หลังจากนั้นจะถูกลบ (ต่อจากนั้นเป็น 404) หากรูปภาพเป็น b64_json การตอบกลับของการดึงข้อมูลก็ใหญ่ตามนั้น (รูปละหลาย MB) — ได้รับแล้วให้เก็บทันที หากผลลัพธ์ทั้งหมดเกิน 16MB จะไม่เก็บรักษาและถือว่าล้มเหลวด้วย IMAGE_JOB_RESULT_TOO_LARGE (ไม่คิดค่าบริการ) — ลดจำนวนรูป (n) หรือความละเอียด
• ID งานของพาร์ทเนอร์อื่น ID ที่ไม่มีอยู่ และ ID ที่เลยระยะเก็บรักษาแล้ว ล้วนได้ 404 IMAGE_JOB_NOT_FOUND เหมือนกัน

API ปฏิทินหมื่นปี

POST /api/v1/partners/v1/manseryeok

รวมอัตลักษณ์ซาจู — ฟิลด์ identity ท้ายการตอบกลับมีสามภัย · ดาวพิเศษ · ช่องว่าง · การหยั่งราก · ความแข็ง-อ่อนตามฤดู · ไทม์ไลน์วัยจร 10 ปี/ดวงรายปี · MBTI ซาจู อยู่ด้วย (ไม่มีค่าบริการเพิ่ม หากคำนวณล้มเหลวจะเป็น null)

คำนวณก้านฟ้า · กิ่งดิน · ฮันจา · ธาตุทั้งห้า · สิบเทพ · ก้านแฝง · นาบึม · 12 วัฏจักรชีวิต · ดาวพิเศษของผังดวง 4 เสา (ปี · เดือน · วัน · ยาม) ด้วยการคำนวณที่แม่นยำตามจุดเปลี่ยนฤดู ให้การตีความซาจูที่สมบูรณ์ตั้งแต่ การวิเคราะห์ผังดวง (ธาตุช่วย · เสริม-กด · ธาตุช่วยปรับฤดู · ความแข็ง-อ่อนของดวง · ความใส-ขุ่น · ธาตุเชื่อม · โรค-ยา · ตัวแปรธาตุทั้งห้า) → วัยจร 10 ปี 10 ช่วง (รวมวัยจรปัจจุบัน · การรวม · ปะทะ · ลงโทษ · ทำร้ายของก้าน-กิ่ง) → ดวงรายปี 5 ปี (ระดับ · ความสัมพันธ์ · การตีความรายปี) → รูปแบบดวง · การตีความโดยละเอียด → ทฤษฎีก้านฟ้า 10 ตัว · สภาพตามฤดู · ช่องว่าง · อักษรแฝง · การรวมลอย · ลาภซ่อน ผ่านฟิลด์พื้นฐานระดับบนสุด 30 ฟิลด์ + ฟิลด์ตัวเลือก (รวมฟิลด์ย่อยกว่า 200 ฟิลด์) หากไม่ทราบเวลาเกิด จะมีเพียงเสายาม (wonkuk.hour) และ trueSolarTime ที่ต้องใช้เวลาจริงเท่านั้นที่เป็น null ส่วนฟิลด์วิเคราะห์อย่างธาตุช่วย · รูปแบบดวง · ความแข็ง-อ่อนของดวง ยังให้ค่าที่คำนวณจาก 3 เสา ปี · เดือน · วัน (6 อักษร) ตามเดิม (birthHour.basis: "three_pillars")

พารามิเตอร์คำขอ

ฟิลด์ในการตอบกลับ (พื้นฐาน 30 ฟิลด์ + ฟิลด์ตัวเลือก)

โครงสร้าง PillarFull (ฟิลด์ย่อยของแต่ละเสา)

ฟิลด์ที่ wonkuk.year · wonkuk.month · wonkuk.day · wonkuk.hour ในการตอบกลับแต่ละตัวมี:

โครงสร้าง DaeunPeriod (แต่ละช่วงของวัยจร 10 ปี)

โครงสร้าง SeunYear (แต่ละปีของดวงรายปี)

ตัวอย่างคำขอ

curl -X POST https://api.hrum.ai/api/v1/partners/v1/manseryeok \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 2000, "month": 1, "day": 15, "hour": 14, "minute": 30,
    "gender": "male", "calendar": "solar", "timezone": "Asia/Seoul"
  }'

ตัวอย่างการตอบกลับ (ตัดตอน: 2000-01-15 14:30 เพศชาย)

{
  "success": true,
  "data": {
    "wonkuk": {
      "year": {
        "stem": "기", "branch": "묘", "stemHanja": "己", "branchHanja": "卯",
        "ohaeng": "토", "stemSipsin": "정관", "branchSipsin": "상관",
        "jijanggan": ["갑", "을"], "chunghyung": [], "hapPosition": ["半合(반합)"],
        "ungSung": "사", "napEum": "성두토",
        "majorSinsal": ["장성살"],
        "minorSinsal": ["천을귀인", "귀문관살", "원진살", "현침살", "육해살"]
      },
      "month": { ... },
      "day": { ... },
      "hour": { ... }
    },
    "trueSolarTime": null,
    "ohaengBalance": { "목": 1, "화": 2, "토": 3, "금": 1, "수": 1 },
    "yongshin": "수",
    "johuYongshin": "화",
    "yongshinDetail": {
      "method": "억부",
      "primary": "수",
      "secondary": ["금"],
      "reasoning": ["일간 임(수) 신약", "신약 + root 있음(8) → 비겁(수)"],
      "shin": { "yongshin": "수", "huishin": "금", "gishin": "토", "gushin": "화", "hanshin": "목" },
      "favorable_sipsin": ["편인", "정인", "비견", "겁재"],
      "unfavorable_sipsin": ["편관", "정관", "편재", "정재", "식신", "상관"],
      "element_states": { "목": { "count": 1, "state": "lack", "effect": "neutral" }, "...": "5오행" }
    },
    "eokbuYongshin": "수",
    "ilganSummary": "壬水 — 큰 바다의 기운. 지혜롭고 포용력이 넓어요.",
    "daeun": [
      {
        "startAge": 3, "endAge": 13,
        "stem": "병", "branch": "자", "stemHanja": "丙", "branchHanja": "子",
        "ohaeng": "화", "isCurrent": false,
        "stemSipsin": "편재", "branchSipsin": "겁재",
        "sinsal": ["년살", "장성살"]
      },
      {
        "startAge": 13, "endAge": 23,
        "stem": "을", "branch": "해", "stemHanja": "乙", "branchHanja": "亥",
        "ohaeng": "목", "isCurrent": false,
        "stemSipsin": "상관", "branchSipsin": "비견",
        "sinsal": ["지살", "망신살"]
      },
      {
        "startAge": 23, "endAge": 33,
        "stem": "갑", "branch": "술", "stemHanja": "甲", "branchHanja": "戌",
        "ohaeng": "목", "isCurrent": true,
        "stemSipsin": "식신", "branchSipsin": "편관",
        "sinsal": ["천살", "월살"]
      }
      // … cycles 4–10 (startAge 33–93) omitted — the actual response has 10
    ],
    "seun": [
      // 2024 and 2025 entries omitted
      {
        "year": 2026, "stem": "병", "branch": "오", "stemHanja": "丙", "branchHanja": "午",
        "ohaeng": "화", "isCurrent": true, "grade": "good",
        "relations": [
          { "type": "해", "target": "월주", "description": "오-축 해" },
          { "type": "육합", "target": "시주", "description": "오-미 육합" }
        ],
        "summary": "전체적으로 순조로운 흐름이 예상돼요. (해, 육합 작용)",
        "sinsal": ["육해살", "재살"]
      }
      // 2027 and 2028 entries omitted — the actual response has 5: two years either side of this year
    ],
    "branchRelations": [
      { "type": "沖(충)", "pillars": ["축", "미"], "description": "丑未沖 (축미충)" },
      { "type": "半合(반합)", "pillars": ["묘", "미"], "description": "卯未合 (묘미합)" }
    ],
    "gongmang": ["술", "해"],
    "cheonEulGwiIn": ["묘"],
    "wolryeong": "축",
    "daeunNumber": 3,
    "daeunDirection": "역행",
    "gyeokguk": {
      "name": "정관격",
      "summary": "질서·명예·합리"
    },
    "gyeokgukDetail": { ... },
    "cheonganDetail": { ... },
    "hapChungReport": { ... },
    "heojaReport": { ... },
    "gongmangDetail": { ... },
    "ohaengByeonsuHits": [
      {
        "key": "to_wang_deuk_mok",
        "subject": "土", "target": "木",
        "formula_idiom": "방능소통(方能疏通)",
        "description": "토가 왕성한데 목을 얻으면 소통이 된다",
        "category": "wang_geuk_sunwha"
      },
      {
        "key": "gang_to_deuk_geum",
        "subject": "土", "target": "金",
        "formula_idiom": "방제기해(方制其害)",
        "description": "강한 토가 금을 얻으면 그 피해를 막는다",
        "category": "gang_seolgi_sunwha"
      }
    ],
    "strength": {
      "dayMaster": "임",
      "score": -66,
      "result": "신약",
      "level": "중약",
      "breakdown": { "season": -30, "support": 8, "control": -38, "hidden": -9, "root": 8 },
      "root": { "rooted": true, "rootScore": 8 }
    },
    "jeongtak": {
      "verdict": "탁",
      "reasons": ["파괴 십신 2개 감지", "용신 금 생 ✓", "일주 신약"],
      "severity": "극탁"
    },
    "tonggwan": { ... },
    "byeongyak": { ... },
    "countryCodeUsed": null,
    "identity": {
      "rooting_hints": { ... }, "season_strength_hint": { ... }, "sinsal_list": [ ... ],
      "gongmang": { ... }, "samjae": { ... }, "timeline": { ... },
      "mbti_inference": { ... }, "coherence": { ... }
    },
    "ohaengDeficient": []
  }
}

ตัวอย่างนี้เป็นผลที่เรียกในปี 2026 ปีของ daeun[].isCurrent · seun จึงเปลี่ยนตามปีที่เรียก บรรทัด { ... } และ // คือเครื่องหมายละ ตัวอย่างนี้เป็นคำขอที่ไม่ได้ส่งตำแหน่ง trueSolarTime จึงเป็น null หากเพิ่ม "country": "KR" (หรือพิกัด) ในคำขอเดียวกัน trueSolarTime จะมีผลการปรับ ("basis": "country") และ countryCodeUsed จะเป็น "KR" รูปแบบผลการปรับดูได้จากตัวอย่างอินพุตจันทรคติในข้อควรระวังด้านล่าง

ข้อควรระวัง

• การตอบกลับที่ซับซ้อน: การตอบกลับของปฏิทินหมื่นปีไม่ได้มีแค่ผังดวง แต่มีข้อมูลละเอียดอย่างวัยจร 10 ปี ดวงรายปี รูปแบบดวง ดาวพิเศษ ฯลฯ เลือกใช้เฉพาะฟิลด์ที่ต้องการ
• ฟิลด์ไม่บังคับ — ข้อตกลงเมื่อไม่ทราบเวลาเกิด: ละ hour · minute ได้ หากละ hour จะไม่สมมติเป็นเที่ยงวัน แต่ตัดเสายามออก การตอบกลับจะต่างไปดังนี้
  • wonkuk.hour = null, trueSolarTime = null
  • ohaengBalance = คำนวณใหม่ตาม 3 เสา ปี · เดือน · วัน (ก้านฟ้า+กิ่งดิน 6 อักษร)
  • branchRelations · cheonEulGwiIn = คงไว้เฉพาะรายการที่เกิดขึ้นได้จากกิ่งดินของ 3 เสา
  • เพิ่ม birthHour ระดับบนสุด: { known: false, hourPillar: null, basis: "three_pillars", excludedFields: [], note } ฟิลด์วิเคราะห์ (yongshin · strength · gyeokguk · hapChungReport · ilganSummary · seun ฯลฯ) ไม่ถูกลบ และส่งเป็นค่าที่คำนวณจาก 3 เสา ปี · เดือน · วัน (6 อักษร) (เกณฑ์ที่ขึ้นกับจำนวนอักษรก็แปลงเป็นเกณฑ์ 6 อักษร) ไม่ใช่ค่าอ้างอิงตามเที่ยงวัน แต่เป็นค่าที่ได้จาก 3 เสาเท่านั้น
  • ใช้ birthHour.known ในการตัดสินว่าไม่ทราบเวลาเกิดหรือไม่ — อย่าตัดสินด้วย excludedFields.length อาร์เรย์นี้ว่างเสมอแล้ว และคงไว้เพื่อความเข้ากันได้กับไคลเอนต์รุ่นเก่าเท่านั้น
  • หากส่ง minute โดยไม่มี hour จะถูกละเว้น (minute ?? 0 เฉพาะเมื่อมี hour)
  • คำขอที่ส่ง hour จะไม่มีฟิลด์ birthHour และผลคำนวณเหมือนเดิม (ยกเว้น identity · ohaengDeficient ที่แนบมาตั้งแต่ 2026-10-10) ไคลเอนต์เดิมที่ส่ง hour เสมอจะไม่ได้รับผลกระทบ ไคลเอนต์ที่สร้างตามพฤติกรรม "หากละไว้จะคำนวณตามเที่ยงวัน" ที่เคยมีอยู่ช่วงสั้นๆ ให้ตรวจ birthHour.known === false แล้วแสดงช่องเสายามเป็น "ไม่ทราบ" strength · gyeokguk ฯลฯ จะส่งเป็นค่าตาม 3 เสาเสมอ (ก่อน 2026-09-16 เคยถูกลบ) กลุ่มการปรึกษา (/reading · /reading/memory · /reading/report) ก็ส่งค่าตาม 3 เสาให้โมเดลด้วยกฎเดียวกัน
• ชื่อฟิลด์ภาษาเกาหลี: ชื่อฟิลด์ทั้งหมด (ก้านฟ้า กิ่งดิน ธาตุทั้งห้า ฯลฯ) เขียนเป็นภาษาเกาหลี แม้ส่ง lang ชื่อฟิลด์ก็ยังคงเดิม และแปลเฉพาะค่า (ธาตุช่วย · คำอธิบายก้านวันเกิด · ทิศทางวัยจร · ชื่อดาวพิเศษ ฯลฯ) รหัสก้านฟ้า · กิ่งดิน · ธาตุทั้งห้า (stem · branch · ohaeng) และคีย์ของ ohaengBalance เป็นฮันกึลเหมือนเดิมในทุกภาษา รายการทั้งหมดดูที่ ค่าที่ใช้ได้ > ค่ารหัสที่ไม่ขึ้นกับภาษา
• ตัวเลือกเพิ่มเติมไม่บังคับทั้งหมด (2026-10-08): หากไม่ส่ง lang · calendar · isLeapMonth · birthLatitude · birthLongitude · country · zaSiRule · birthTimePrecision เลย ผลคำนวณจะเหมือนเดิม แต่ตั้งแต่ 2026-10-10 จะเพิ่ม identity · ohaengDeficient ท้ายการตอบกลับเสมอ (ค่า · ลำดับของคีย์เดิมคงเดิม) ราคาก็ยังเป็น ₩50/ครั้งเหมือนเดิม
• เปลี่ยนแปลง (2026-10-12): เปลี่ยนเกณฑ์การแปลงจันทรคติเป็นข้อมูลของสถาบันดาราศาสตร์และอวกาศเกาหลี (KASI) ผลของบางวันที่เปลี่ยนไป เดือนอธิกมาสที่ไม่มีอยู่จะไม่เปลี่ยนเป็นเดือนปกติ แต่ตอบด้วย 400 INVALID_LUNAR_DATE
• อินพุตจันทรคติ: หากส่ง calendar: "lunar" ระดับบนสุดของการตอบกลับจะมีรายละเอียดการแปลง lunarInput แนบมา ผลการปรับเวลาสุริยะจริงอยู่ใน trueSolarTime ตัวอย่างผลลัพธ์จริงของเอนจิน (จันทรคติ 1990-07-15 14:30 พิกัดปูซาน lang: "en"):

  {
    "year": 1990, "month": 7, "day": 15, "hour": 14, "minute": 30,
    "timezone": "Asia/Seoul", "gender": "male",
    "calendar": "lunar", "birthLatitude": 35.1796, "birthLongitude": 129.0756,
    "lang": "en"
  }
  →
  "lunarInput": {
    "calendar": "lunar", "lunarDate": "1990-07-15", "isLeapMonth": false,
    "leapMonthApplied": false, "solarDate": "1990-09-03"
  },
  "trueSolarTime": {
    "originalLocal": "14:30", "correctedLocal": "14:07",
    "longitudeCorrection": -23.6976, "equationOfTime": 0.3241,
    "totalCorrectionMinutes": -23.4, "dayShift": 0, "dstApplied": false,
    "basis": "coords", ...
  },
  "ilganSummary": "辛 Metal — Jewel energy. Sharp intellect and refined aesthetic sense.",
  "daeunDirection": "Forward"

• อินพุตผิดพลาด: วันที่จันทรคติที่ไม่มีอยู่จริง (เช่น วันที่ 30 ของเดือนที่มีถึงวันที่ 29) จะได้ 400 INVALID_LUNAR_DATE คำขอที่ส่งละติจูด/ลองจิจูดเพียงค่าเดียวจะได้ 400 INVALID_LOCATION และไม่คิดค่าบริการ ข้อผิดพลาดด้านรูปแบบ เช่น ไม่มี timezone ก็ได้ 400 (ไม่คิดค่าบริการ)

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

{
  "year": 1990, "month": 9, "day": 4, "hour": 14, "minute": 30,
  "timezone": "Asia/Seoul", "gender": "male",
  "topic": "career", "lang": "ko"
}

{
  "success": true,
  "data": {
    "topics": [
      {
        "topic": "career",
        "paragraphs": [
          { "component": "ilju", "key": "임신", "text": "..." },
          { "component": "ilgan_wolji", "key": "임_신", "text": "..." },
          { "component": "ilgan_strength", "key": "임_신강", "text": "..." },
          { "component": "ilgan_yongshin", "key": "임_화", "text": "..." },
          { "component": "ohaeng_state", "key": "목_lack", "text": "..." },
          { "component": "ohaeng_state", "key": "토_lack", "text": "..." },
          { "component": "ohaeng_state", "key": "수_lack", "text": "..." },
          { "component": "top_sipsin", "key": "인성", "text": "..." }
        ]
      }
    ],
    "lang": "ko",
    "fallbackLanguage": null,
    "engine": { "version": 1, "styleVersion": "v1" }
  }
}

{
  "year": 1990, "month": 9, "day": 4, "hour": 14, "minute": 30,
  "timezone": "Asia/Seoul", "gender": "male",
  "birthLatitude": 37.5665, "birthLongitude": 126.978,
  "topic": "career", "lang": "ko",
  "layers": ["astro", "ziwei"]
}

{
  "success": true,
  "data": {
    "topics": [
      {
        "topic": "career",
        "paragraphs": [
          { "component": "ilju", "key": "임신", "text": "..." },
          ...
          { "component": "top_sipsin", "key": "인성", "text": "..." },
          { "component": "astro_sun", "key": "vir", "text": "...", "label": "별자리로 보면" },
          { "component": "astro_moon", "key": "pis", "text": "..." },
          { "component": "astro_asc", "key": "sag", "text": "..." },
          { "component": "ziwei_ming", "key": "tt_jm", "text": "...", "label": "자미두수로 보면" },
          { "component": "ziwei_palace", "key": "cr_tj", "text": "..." }
        ]
      }
    ],
    "lang": "ko",
    "fallbackLanguage": null,
    "engine": { "version": 1, "styleVersion": "v1" },
    "missingSections": 0,
    "layers": {
      "astro": { "included": true, "costWon": 20, "note": null },
      "ziwei": { "included": true, "costWon": 20, "note": null }
    }
  }
}

{
  "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30,
  "gender": "female", "referenceDate": "2026-10-08", "lang": "ko"
}

{
  "success": true,
  "data": {
    "engineVersion": 1,
    "lang": "ko",
    "referenceDate": "2026-10-08",
    "clock": {
      "inputSolarDate": "1990-05-15", "inputTime": "14:30",
      "correctedSolarDate": "1990-05-15", "correctedTime": "14:30",
      "correctionMinutes": 0, "dstApplied": false, "basis": null,
      "hourBranch": { "key": "wei", "label": "미" }
    },
    "chart": {
      "engine": { "name": "iztro", "version": "2.6.1", "config": { ... } },
      "solarDate": "1990-05-15",
      "lunarDate": { "year": 1990, "month": 4, "day": 21, "isLeapMonth": false },
      "yearGanzhi": "경오",
      "yearBasisNote": null,
      "fiveElementsClass": { "key": "earth5", "label": "토오국" },
      "soulPalaceBranch": { "key": "xu", "label": "술" },
      "bodyPalaceBranch": { "key": "zi", "label": "자" },
      "palaces": [
        ...,
        {
          "key": "ming", "label": "명궁",
          "branch": { "key": "xu", "label": "술" },
          "stem": { "key": "bing", "label": "병" },
          "isBodyPalace": false,
          "majorStars": [
            { "key": "ziwei", "label": "자미", "brightness": { "key": "de", "label": "득" }, "mutagen": null },
            { "key": "tianxiang", "label": "천상", "brightness": { "key": "de", "label": "득" }, "mutagen": null }
          ],
          "minorStars": [
            { "key": "lingxing", "label": "영성", "brightness": { "key": "miao", "label": "묘" }, "mutagen": null }
          ],
          "decadal": { "from": 5, "to": 14, "isCurrent": false }
        },
        ...
      ],
      "mutagens": [
        { "type": "lu", "label": "화록", "starKey": "taiyang", "starLabel": "태양", "palaceKey": "children", "palaceLabel": "자녀궁" },
        { "type": "quan", "label": "화권", "starKey": "wuqu", "starLabel": "무곡", "palaceKey": "wealth", "palaceLabel": "재백궁" },
        { "type": "ke", "label": "화과", "starKey": "taiyin", "starLabel": "태음", "palaceKey": "children", "palaceLabel": "자녀궁" },
        { "type": "ji", "label": "화기", "starKey": "tiantong", "starLabel": "천동", "palaceKey": "health", "palaceLabel": "질액궁" }
      ],
      "currentDecadal": { "palaceKey": "children", "from": 35, "to": 44 },
      "yearly": { "palaceKey": "wealth", "year": 2026 }
    },
    "features": [
      "bright:紫微=得", "co:紫微+天相@命", "cs:命=胎", "dir:逆", "hua:祿=太陽@子女",
      "lhua:忌=廉貞@流年", "limit:大限@子女", "limit:小限@辰", "ming:戌", "mingzhu:祿存",
      "star:天姚@辰", "star:紫微@命", "year:庚", "yy:陽女", ...
    ],
    "notes": { "lateZiNotice": null, "approximateTimeNote": null }
  }
}

{
  "success": false,
  "statusCode": 400,
  "code": "birth_time_required",
  "message": "Zi Wei Dou Shu needs the birth hour (hour 0-23). ...",
  "partial": {
    "birthYearMutagens": [
      { "type": "lu", "label": "화록", "starKey": "taiyang", "starLabel": "태양" },
      ...
    ],
    "yearStemStars": [
      { "key": "lucun", "label": "녹존", "branch": { "key": "shen", "label": "신" } },
      ...
    ]
  }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/identity \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0, "timezone": "Asia/Seoul", "gender": "male" }'

{
  "success": true,
  "data": {
    "saju": {
      "year":  { "cheongan": "경", "jiji": "오", "ohaeng": "금" },
      "month": { "cheongan": "신", "jiji": "사", "ohaeng": "금" },
      "day":   { "cheongan": "경", "jiji": "진", "ohaeng": "금" },
      "hour":  { ... }
    },
    "sipsin_map": { "year_cheongan": "비견", "year_jiji": "정관", "month_cheongan": "겁재", ... },
    "strength": { "dayMaster": "경", "score": -60, "result": "신약", "level": "중약", ... },
    "rooting_hints": { ... },
    "season_strength_hint": { "season": "여름", "strength_label": "최약(最弱)", ... },
    "sinsal_list": [ { "id": "shinsal_haksang", "name": "학당", "name_hanja": "學堂", "category": "길신", ... } ],
    "gongmang": { "sun": "갑술순", "void_branches": ["신", "유"], "hits": [] },
    "samjae": { "is_in_samjae": false, "current_year_branch": "오" },
    "yongshin": { "method": "조후", "primary": "수", ... },
    "timeline": { "current": { "daeun": { "startAge": 27, "endAge": 37, "stem": "갑", "branch": "신", ... }, ... } },
    "gyeokguk": { "primary": "비견격", ... },
    "mbti_inference": { "e_i": 48, "s_n": -8, "t_f": 16, "j_p": -18, "inferred": "ESFJ", ... },
    ...
  }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/saju-mbti \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0, "timezone": "Asia/Seoul", "gender": "male", "mbti": "INFJ" }'

{
  "success": true,
  "data": {
    "wonkuk": {
      "year":  { "cheongan": "경", "jiji": "오", "ohaeng": "금" },
      "month": { "cheongan": "신", "jiji": "사", "ohaeng": "금" },
      "day":   { "cheongan": "경", "jiji": "진", "ohaeng": "금" },
      "hour":  { "cheongan": "임", "jiji": "오", "ohaeng": "수" }
    },
    "pillarCount": 4,
    "dayMaster": "경",
    "strength": "신약",
    "ohaengCount": { "목": 0, "화": 3, "토": 1, "금": 3, "수": 1 },
    "ohaengState": { "목": "lack", "화": "balanced", "토": "lack", "금": "balanced", "수": "lack" },
    "dominantSipseong": ["관성"],
    "mbti": {
      "type": "INFJ",
      "source": "letters",
      "axes": {
        "E_I": { "value": 25, "letter": "I", "band": "slight" },
        "S_N": { "value": 25, "letter": "N", "band": "slight" },
        "T_F": { "value": 25, "letter": "F", "band": "slight" },
        "J_P": { "value": 75, "letter": "J", "band": "slight" }
      }
    },
    "sajuLean": {
      "E_I": { "lean": "balanced", "weights": { "E": 1, "I": 1 }, "ruleIds": ["R-MBTI-OHAENG-010", "R-MBTI-STRENGTH-002"] },
      "S_N": { "lean": "S", "weights": { "S": 1 }, "ruleIds": ["R-MBTI-OHAENG-006"] },
      "T_F": { "lean": "T", "weights": { "T": 2 }, "ruleIds": ["R-MBTI-STEM-007"] },
      "J_P": { "lean": "J", "weights": { "P": 1, "J": 2 }, "ruleIds": ["R-MBTI-OHAENG-008", "R-MBTI-SIPSEONG-002"] }
    },
    "comparison": [
      { "axis": "E_I", "label": "에너지 방향(E·I)", "user": "I", "userBand": "slight", "saju": "balanced", "relation": "neutral",
        "text": "에너지 방향(E·I): 사주에서는 어느 한쪽으로 기우는 경향이 뚜렷하지 않아요. 입력은 I 쪽이에요." },
      { "axis": "S_N", "label": "인식 방식(S·N)", "user": "N", "userBand": "slight", "saju": "S", "relation": "different",
        "text": "인식 방식(S·N): 사주와 다른 면을 키운 것으로 볼 수 있어요. 사주는 S 쪽 경향이 있고, 입력은 N 쪽이에요." },
      { "axis": "T_F", ... },
      { "axis": "J_P", "label": "생활 방식(J·P)", "user": "J", "userBand": "slight", "saju": "J", "relation": "same",
        "text": "생활 방식(J·P): 사주와 같은 방향이에요. 사주에서 보이는 J 쪽 경향이 입력에도 드러나요." }
    ],
    "matchedRules": [
      { "id": "R-MBTI-STEM-007", "statement": "庚 일간은 단단한 쇠의 기운으로 읽혀, 기준을 세워 따져 보고 결단하는 쪽(T)으로 기울기 쉬운 경향이 있어요." },
      ...
    ],
    "caveats": [ { "id": "R-MBTI-CAVEAT-001", "statement": "사주와 MBTI를 잇는 이 해석은 고전 명리 이론이 아니라 현대의 해석 관행이에요. ..." }, ... ],
    "caveatRuleId": "R-MBTI-CAVEAT-001",
    "interim": false,
    "kbStatus": "literature",
    "kbVersion": "2026.10.16-2",
    "engineVersion": "saju-mbti-1"
  }
}

{
  "year": 1990, "month": 5, "day": 15, "hour": 12, "minute": 0,
  "timezone": "Asia/Seoul", "gender": "male",
  "date": "2026-10-10",
  "temperatureC": 16, "weather": "cloudy", "humidity": 60,
  "mbtiBehavior": true
}

{
  "success": true,
  "data": {
    "date": "2026-10-10",
    "summary": {
      "ilju": "경진",
      "day_master": "경",
      "gyeokguk": "비견격",
      "gyeokguk_reason": "월지 사 중기(경) 투간 [연간=경]",
      "inferred_mbti": "ESFJ",
      "today_mbti": "ESFJ",
      "current_mbti": "ESFJ",
      "strength_label": "신약",
      "yongshin": "수",
      "today_date": "2026-10-10",
      "today_ganji": "정사",
      "today_day_ohaeng": "화",
      "today_sipsin": "정관",
      "flow_score": 60,
      "flow_tier": "good",
      "top_favored_task_type": "routine",
      "top_caution_task_type": "movement",
      "active_sinsal_names": ["학당", "암록", "복성귀인", "화개살", "자형(오오)"],
      "in_samjae": false,
      "daily_flow": "오늘(정사일) 화 에너지가 흘러 소통·확장에 유리해."
    },
    "omen": {
      "relation": { "type": "GEUK", "label": "조율의 날" },
      "color": { "name": "주황", "hex": "#FFA45B", "ohaeng": "화" },
      "food": "고추장비빔밥",
      "keyword": "공개",
      "message": "표현하고 싶은 마음과 주변 반응이 엇갈릴 수 있는 날이에요. 즉흥적인 말보다 한 박자 늦춘 표현이 좋아요.",
      "luckyHour": "오전 11시 ~ 오후 1시",
      "avoidHour": "밤 11시 이후",
      "activity": "칭찬 먼저 하기"
    },
    "taskAffinity": [
      { "taskType": "focus", "score": -0.25, "verdict": "neutral",
        "reason": "길 십신 2개 일치 · 흉 십신 2개 일치 · 일진 천간 정관(흉) · 일진 지지 편관(흉) · 천간합" },
      { "taskType": "creative", "score": -0.75, "verdict": "caution", "reason": "..." },
      ...,
      { "taskType": "routine", "score": 0.25, "verdict": "favored",
        "reason": "길 십신 4개 일치 · 일진 천간 정관(흉) · 일진 지지 편관(흉) · 천간합" }
    ],
    "fashion": {
      "temperatureC": 16, "tempBand": "T3",
      "main": "버건디 자켓", "accent": "가죽 벨트",
      "colorAttachLabel": "반지나 메탈 액세서리에",
      "byTime": {
        "morning": { "main": "버건디 자켓", "accent": "가죽 벨트", "tempBand": "T3" },
        "noon": { ... }, "evening": { ... }
      },
      "mood": {
        "feelsLikeC": 16, "tempBand": "jacket", "humidBand": "normal", "weatherKey": "cloudy",
        "morning": { "headline": "흐린 자켓 새벽", "body": "햇볕 없어 살짝 서늘. 자켓 한 벌.", "carry": [] },
        "noon": { ... }, "evening": { ... }
      }
    },
    "mbtiBehavior": {
      "mbti": "ESFJ",
      "headline": "협력·돌봄",
      "actions": ["약속·일정 챙기기 좋은 날", "주변에 도움 줄 수 있는 일 1개", "집·환경 정돈", "내 페이스도 지키기 — 다 떠안지 않기"],
      "closingLine": "주변과 결이 맞아 흐름이 부드러워요."
    }
  }
}

{
  "dream": "바다에서 커다란 물고기를 두 손으로 잡는 꿈을 꿨어요"
}

{
  "success": true,
  "data": {
    "lang": "ko",
    "mode": "glossary",
    "items": [
      { "keywords": ["바다"], "score": 1 },
      { "keywords": ["물고기"], "score": 0.979 },
      { "keywords": ["손"], "score": 0.749 }
    ]
  }
}

"kbMatches": [
  {
    "ruleId": "R-DREAM-DRAGON-002",
    "area": "DRAGON",
    "polarity": "positive",
    "status": "verified",
    "statement": "“주공해몽서”(돈황본 P.3908, 第十二 龍蛇章)는 뱀(虵=蛇)이 길에 있는 꿈(夢見虵當道者)에 대해 “大吉”라고 적는다(글자대로: 크게 길하다).",
    "quote": {
      "text": "夢見虵當道者大吉",
      "sourceId": "SRC-DREAM-P3908",
      "source": "“周公解夢書” (敦煌 P.3908)",
      "location": "P.3908 第十二 龍蛇章 f09/左/行3下",
      "foundAt": "dream-pd/dunhuang-p3908-bnf/P3908-TRANSCRIPTION-merged.md:198"
    },
    "caveatRuleIds": [],
    "matchedTerms": ["구렁이", "길"]
  }
]

{
  "modelName": "face_landmarker",
  "modelVersion": "float16/[email protected]",
  "normalization": "face-norm-1",
  "landmarks": [[0.5012, 0.3121, -0.031], … 478개 …],
  "imageWidth": 1080,
  "imageHeight": 1350,
  "hairline": [0.501, 0.182],
  "quality": { "yawDeg": 2.1, "pitchDeg": -3.4, "blendshapes": { "eyeBlinkLeft": 0.05, "jawOpen": 0.02 } }
}

{
  "success": true,
  "data": {
    "normalization": "face-norm-1",
    "keys": { "face.thirds.upper_ratio": 0.3333, "face.brow.length_vs_eye": 1.625, "face.brow.outer_overhang": 0.1648, … },
    "reasons": {},
    "quality": { "rollDeg": 0, "iodPx": 158, "flags": [] },
    "kbMatches": [
      {
        "ruleId": "R-FACE-PALACE-031",
        "area": "PALACE",
        "kind": "interpretation",
        "polarity": "positive",
        "status": "verified",
        "statement": "“古今圖書集成” 相術部彙考 “十二宮訣” 兄弟는 눈썹이 눈보다 길게 지나가면(眉長過目) …라고 적는다 …",
        "quote": { "text": "眉長過目，三四兄弟", "sourceId": "SRC-FACE-HUIKAO", "source": "…", "location": "…", "foundAt": "…" },
        "caveatRuleIds": ["R-FACE-CAVEAT-001"],
        "matchedConditions": [{ "key": "face.brow.outer_overhang", "op": "gt", "value": 0, "actual": 0.1648 }]
      }
    ]
  }
}

{
  "image": { "data": "/9j/4AAQSkZJRgABAQ…(base64)", "mimeType": "image/jpeg" },
  "consent": { "photo": true, "version": "photo-consent-2026-10", "subject": "end_user" },
  "lang": "ko",
  "endUserId": "member-1024"
}

{
  "image": { "data": "/9j/4AAQSkZJRgABAQ…(base64)", "mimeType": "image/jpeg" },
  "consent": { "photo": true, "version": "photo-consent-2026-10", "subject": "end_user" },
  "creases": [
    { "line": "life", "points": [[0.42, 0.38], [0.36, 0.52], [0.34, 0.71]] },
    { "line": "heart", "points": [[0.78, 0.33], [0.6, 0.31], [0.47, 0.34]] }
  ]
}

"processing": {
  "provider": "OpenAI",
  "model": "gpt-5.6-luna",
  "region": "US",
  "store": false,
  "retention": "API 입력은 학습에 쓰지 않음, 오남용 감시로 최대 30일 보관 뒤 삭제",
  "imageStored": false
}

{
  "success": true,
  "data": {
    "items": [
      {
        "key": "forehead",
        "label": "이마",
        "observation": "이마가 넓고 둥글게 보여요.",
        "reason": "넓은 이마는 생각을 넓게 펼치는 쪽으로 읽혀요. 떠오른 계획을 글로 정리해 두면 장점이 더 살아나요."
      },
      {
        "key": "eyes",
        "label": "눈",
        "observation": "눈매가 길고 가로로 뻗어 있어요.",
        "reason": "긴 눈매는 사람과 상황을 찬찬히 살피는 쪽으로 읽혀요."
      }
    ],
    "summary": "생각을 넓게 펼치고 찬찬히 살피는 인상으로 읽혀요.",
    "lang": "ko",
    "meta": {
      "input": "image",
      "processing": { "provider": "OpenAI", "model": "gpt-5.6-luna", "region": "US", "store": false, "retention": "API 입력은 학습에 쓰지 않음, 오남용 감시로 최대 30일 보관 뒤 삭제", "imageStored": false },
      "disclaimer": "entertainment_reference",
      "disclaimerText": "전통 관상·손금·성명학을 재미와 참고로 풀어 본 내용이에요. 사실 판단이나 진단이 아니에요.",
      "kbRuleIds": []
    }
  }
}

{
  "name": { "hangul": "김민수", "hanja": ["金", "民", "秀"], "strokes": [null, 5, 7], "meanings": ["쇠", null, null] },
  "birth": { "year": 1990, "month": 5, "day": 17, "hour": 9 },
  "consent": { "version": "name-consent-2026-10", "subject": "end_user" }
}

{
  "success": true,
  "data": {
    "name": { "hangul": "김민수", "hanja": ["金", "民", "秀"] },
    "deterministic": {
      "surnameLength": 1,
      "syllables": [
        { "index": 0, "hangul": "김", "hanja": "金", "strokes": 8, "strokeSource": "kb", "strokeNote": null, "strokeRuleId": "R-NAME-STROKE-004", "soundElement": "wood", "soundRuleId": "R-NAME-SOUND-004", "meaning": "쇠", "rootElement": "metal" },
        { "index": 1, "hangul": "민", "hanja": "民", "strokes": 5, "strokeSource": "input", "strokeNote": null, "strokeRuleId": null, "soundElement": "water", "soundRuleId": "R-NAME-SOUND-010", "meaning": null, "rootElement": null },
        { "index": 2, "hangul": "수", "hanja": "秀", "strokes": 7, "strokeSource": "input", "strokeNote": null, "strokeRuleId": null, "soundElement": "metal", "soundRuleId": "R-NAME-SOUND-006", "meaning": null, "rootElement": null }
      ],
      "soundFlow": { "elements": ["wood", "water", "metal"], "relations": ["reverse_generating", "reverse_generating"], "generating": 0, "overcoming": 0, "score": 0.5 },
      "suri": {
        "won": { "sum": 12, "number": 12, "grade": "bad" },
        "hyung": { "sum": 13, "number": 13, "grade": "good" },
        "i": { "sum": 15, "number": 15, "grade": "good" },
        "jeong": { "sum": 20, "number": 20, "grade": "bad" }
      },
      "suriMissing": null,
      "yongshin": { "element": "wood", "supplied": true, "suppliedBy": ["sound"] },
      "kbRuleIds": ["R-NAME-JAWON-001", "R-NAME-MODERN-001", "R-NAME-MODERN-003", "R-NAME-SOUND-004", "R-NAME-SOUND-006", "R-NAME-SOUND-010", "R-NAME-SOUND-011", "R-NAME-STROKE-004"]
    },
    "interpretation": { "text": "첫 글자는 목, 가운데 글자는 수, 끝 글자는 금 기운이에요. 소리가 서로 부딪치지 않고 이어지는 이름으로 읽혀요." },
    "items": [
      { "key": "sound_flow", "label": "발음오행 흐름", "score": 0.5, "reason": "김(목(木)) → 민(수(水)) → 수(금(金)) · 상생 0 · 상극 0", "ruleId": "R-NAME-SOUND-011" },
      { "key": "suri_hyung", "label": "형격", "grade": "good", "score": 13, "reason": "획수 합 13 → 13수(길)", "ruleId": "R-NAME-MODERN-001" },
      { "key": "yongshin_match", "label": "용신 보완", "grade": "supplied", "reason": "용신 목(木)을 이름이 발음으로 채워 줘요" }
    ],
    "summary": "부드럽게 이어지는 소리에 용신 기운이 담긴 이름으로 읽혀요.",
    "lang": "ko",
    "meta": {
      "input": "name",
      "processing": { "provider": "OpenAI", "model": "gpt-5.6-luna", "region": "US", "store": false, "retention": "API 입력은 학습에 쓰지 않음, 오남용 감시로 최대 30일 보관 뒤 삭제", "imageStored": false },
      "disclaimer": "entertainment_reference",
      "disclaimerText": "전통 관상·손금·성명학을 재미와 참고로 풀어 본 내용이에요. 사실 판단이나 진단이 아니에요.",
      "kbRuleIds": ["R-NAME-JAWON-001", "R-NAME-MODERN-001", "R-NAME-MODERN-003", "R-NAME-SOUND-004", "R-NAME-SOUND-006", "R-NAME-SOUND-010", "R-NAME-SOUND-011", "R-NAME-STROKE-004"]
    }
  }
}

API ไพ่ทาโรต์

POST /api/v1/partners/v1/tarot

เมื่อกำหนดจำนวนใบ (count 1~10 ใบ) หรือรูปแบบการวางไพ่ (spread) จะสุ่มไพ่จากสำรับ 78 ใบ (เมเจอร์ 22 · ไมเนอร์ 56) โดยไม่ซ้ำกัน แล้วคืนหัวตั้ง · หัวกลับ คีย์เวิร์ด ความหมาย ที่อยู่รูปไพ่ของแต่ละใบ ไม่มีการตีความโดย AI — ความหมายคือประโยคที่กำหนดไว้ของไพ่ตามเดิม จึงมีวิธีใช้สามแบบ

• เรียกไพ่ทาโรต์อย่างเดียวเพื่อสร้างแอป — นำชื่อไพ่ · ความหมาย · รูปในการตอบกลับไปแสดงบนหน้าจอตามเดิม
• ไพ่ทาโรต์ + LLM เพื่อตีความ — ส่งไพ่ที่สุ่มได้เป็นอินพุตของ LLM API แล้วเขียนคำอ่านเอง
• ใช้ร่วมกับ AI ซาจู — หากใส่ tarot ในคำขอ AI อ่านดวงซาจู จะอ่านไพ่ทาโรต์ไปพร้อมกับการอ่านซาจู (รายการที่รวมอยู่)

พารามิเตอร์คำขอ

ตัวอย่างคำขอ

{
  "spread": "past-present-future",
  "question": "올해 하반기에 이직해도 될까요?",
  "seed": "user-1042:2026-10-10"
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/tarot \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 1, "lang": "en", "reversed": false}'

ตัวอย่างการตอบกลับ (ตัดตอนไพ่ 1 ใบ)

{
  "success": true,
  "data": {
    "lang": "ko",
    "count": 3,
    "spread": { "type": "past-present-future", "name": "과거·현재·미래", "description": "시간 흐름을 따라가는 질문", "positions": ["과거", "현재", "미래"] },
    "reversedAllowed": true,
    "seed": "hrum-example-1",
    "cards": [
      {
        "position": 1,
        "positionLabel": "과거",
        "id": "wands_10",
        "name": "완드의 10",
        "nameEn": "Ten of Wands",
        "arcana": "wands",
        "reversed": true,
        "keywords": ["내려놓기", "위임", "해방"],
        "meaning": "무거운 짐을 마침내 내려놓거나 도움을 받기 시작하는 시기.",
        "imageUrl": "https://console.hrum.ai/tarot/cards/v2/wands_10.webp"
      }
    ],
    "cardBackUrl": "https://console.hrum.ai/tarot/cards/v2/back.webp",
    "question": "올해 하반기에 이직해도 될까요?",
    "costPoints": 20
  }
}

• cards[]: position (เริ่มจาก 1 ลำดับที่สุ่ม = ตำแหน่งในรูปแบบการวาง) · positionLabel (ชื่อตำแหน่งในรูปแบบการวาง หากสุ่มด้วย count เป็น null) · id (ค่าเฉพาะของไพ่ที่ไม่ขึ้นกับภาษา) · name (ภาษาที่ขอ) · nameEn · arcana (major | wands | cups | swords | pentacles) · reversed · keywords · meaning (ของทิศทางที่สุ่มได้) · imageUrl
• spread: หากสุ่มด้วย count จะเป็น null
• รูปไพ่: imageUrl · cardBackUrl เป็น WebP (กว้าง 600px) และที่อยู่มีเวอร์ชัน (v2) จึงไม่เปลี่ยน — ดาวน์โหลดมาแคชไว้แล้วใช้ตามเดิมได้ ไพ่หัวกลับให้หมุนรูป 180 องศาเพื่อแสดง (ตัวรูปมีแบบหัวตั้งแบบเดียว)
• แหล่งที่มาของภาพ: สแกนจากต้นฉบับ Rider-Waite ปี 1909 (Pamela Colman Smith สาธารณสมบัติ) ไพ่ทั้ง 78 ใบและด้านหลังเป็นสแกนต้นฉบับปี 1909 จาก Wikimedia Commons แหล่งที่มา · สัญญาอนุญาตของแต่ละไฟล์อยู่ในบัญชีแหล่งที่มา ที่อยู่เดิม (v1) ก็ยังคืนรูปเดียวกัน จึงไม่ต้องเปลี่ยนที่อยู่ที่เก็บไว้แล้ว
• costPoints: ยอดที่หักในการเรียกครั้งนี้ (₩)

ราคา

• ค่าบริการคงที่ 1 ครั้งต่อการเรียก — สุ่ม 1 ใบหรือ 10 ใบก็เท่ากัน ราคาอยู่ในตารางแบบคำนวณของราคา คิดค่าบริการเฉพาะการเรียกที่สำเร็จ และการเรียกซ้ำด้วยอินพุตเดิมก็คิดค่าบริการแยกกัน (Idempotency)
• อินพุตผิดพลาด (400) · ยอดคงเหลือไม่พอ (402) ไม่คิดค่าบริการ endpoint ในบันทึกการใช้งานคือ tarot
• หากเรียกขณะที่ยังไม่เปิด จะได้ 404 tarot_not_enabled (ไม่คิดค่าบริการ)

หลักฐานจากต้นฉบับ Waite kb

เมื่อเปิดแล้ว การตอบกลับจะมี kb แนบมา สำหรับไพ่แต่ละใบที่สุ่มได้ จะคืนความหมายหัวตั้ง · หัวกลับของไพ่ใบนั้นจากต้นฉบับ A. E. Waite, The Pictorial Key to the Tarot (1910 สาธารณสมบัติ) พร้อม ID กฎ (R-TAROT-*) และการอ้างอิงต้นฉบับ meaning · keywords ข้างต้นคงเดิม เพิ่มเพียง kb และราคาเท่าเดิม

• kb.cards[]: position · id · reversed · drawn (ความหมายของทิศทางที่สุ่มได้) · upright · reversedMeaning · positionRule แต่ละความหมายมี ruleId · status · statement (ภาษาเกาหลี) · quotes[] (quote ต้นฉบับภาษาอังกฤษ location บทและตอน foundAt บรรทัดในต้นฉบับ) · variants[] (คำอธิบายอื่นที่ Waite เขียนไว้ alternative ความหมายเพิ่มเติมจากภาค 3 §4 additional)
• status ใช้ตามที่ KB ระบุ (verified = มีการอ้างอิงต้นฉบับ) ตำแหน่งที่ Waite ไม่ได้เขียนความหมายไว้ (ไพ่ถ้วย 2 หัวกลับ) จะเป็น ruleId: null, status: "disputed"
• method: "celtic-cross": วิธีดูไพ่แบบเซลติกที่ Waite เขียนไว้ในหนังสือ (10 ใบ) ส่งแทน count · spread และความหมายตำแหน่งของ Waite สำหรับแต่ละตำแหน่งของ 10 ใบจะอยู่ใน positionRule spread อื่นเป็นการจัดวางที่ไม่มีในต้นฉบับของ Waite จึงไม่มีหลักฐานของตำแหน่ง (kb.method: null)
• kb.caveats: คำของ Waite ที่ว่าความหมายเปลี่ยนตามตำแหน่ง และหลักการใช้งาน (เป็นเครื่องมือการดูดวง ไม่ได้แทนการตัดสินใจด้านสุขภาพ · กฎหมาย · การเงิน)
• หากส่ง method ก่อนเปิด จะได้ 404 tarot_kb_not_enabled (ไม่คิดค่าบริการ)

{
  "method": "celtic-cross",
  "seed": "user-1042:2026-10-11"
}

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

ต้องส่ง count · spread · method อย่างใดอย่างหนึ่งพอดี หากส่งสองอย่างขึ้นไปหรือไม่ส่งเลยจะได้ 400 ทั่วไป

API ผังดวงกำเนิด (Natal Chart) (โหราศาสตร์ตะวันตก) เลิกจำหน่าย

POST /api/v1/partners/v1/natal-chart

คำนวณผังดวงกำเนิดของโหราศาสตร์ตะวันตก (ตำแหน่งดาว 7 ดวง ดวงอาทิตย์ · ดวงจันทร์ · ดาวพุธ · ดาวศุกร์ · ดาวอังคาร · ดาวพฤหัสบดี · ดาวเสาร์ + ลัคนา) จากวันเดือนปีและเวลาเกิด ไม่รวมดาวยูเรนัส · เนปจูน · พลูโต ใช้จักรราศีแบบทรอปิคัลของโหราศาสตร์ตะวันตก ไม่ใช่จุดเปลี่ยนฤดู

พารามิเตอร์คำขอ

ฟิลด์ในการตอบกลับ

ตัวอย่างคำขอ

curl -X POST https://api.hrum.ai/api/v1/partners/v1/natal-chart \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1990-05-15",
    "birthTime": "12:00",
    "birthLatitude": 37.5665,
    "birthLongitude": 126.978,
    "birthTimezoneOffset": 540,
    "birthTimePrecision": "exact"
  }'

ตัวอย่างการตอบกลับ

{
  "success": true,
  "data": {
    "sun": {
      "body": "Sun",
      "sign": "황소자리",
      "signEn": "Taurus",
      "element": "흙",
      "degreeInSign": 24.03,
      "eclipticLongitude": 54.0343
    },
    "moon": { "body": "Moon", "sign": "염소자리", "signEn": "Capricorn", "element": "흙", ... },
    "mercury": { "body": "Mercury", "sign": "황소자리", "signEn": "Taurus", ... },
    "venus": { "body": "Venus", "sign": "양자리", "signEn": "Aries", "element": "불", ... },
    "mars": { ... },
    "jupiter": { ... },
    "saturn": { ... },
    "ascendant": {
      "body": "Ascendant",
      "sign": "사자자리",
      "signEn": "Leo",
      "element": "불",
      "degreeInSign": 23.13,
      "eclipticLongitude": 143.1256
    },
    "coordsBasis": "coords",
    "engineVersion": "natal-2"
  }
}

คำขอของตัวอย่างข้างต้น: {"birthDate": "1990-05-15", "birthTime": "12:00", "birthLatitude": 37.5665, "birthLongitude": 126.978, "birthTimezoneOffset": 540, "birthTimePrecision": "exact"} (ตัดตอนผลลัพธ์จริงของเอนจิน)

{
  "success": true,
  "data": {
    "sun": { ... }, "moon": { ... }, ...,
    "readings": {
      "dignities": [
        { "key": "Me_dom", "lang": "ko",
          "text": "수성이 본궁인 쌍둥이자리나 처녀자리에 있으면 정보를 모으고 분류해 말로 옮기는 기능이 막힘없이 또렷하게 드러나요. 생각이 많아질 때 하나를 골라 끝까지 파고들면 그 명료함이 실제 성과로 이어져요." },
        { "key": "Sa_dom", "lang": "ko",
          "text": "토성이 본궁인 염소자리나 물병자리에 있으면 책임을 지고 구조를 세워 반복 훈련으로 숙련을 쌓는 기능이 막힘없이 또렷하게 드러나요. 기준이 지나치게 굳어질 때 쉬어 갈 틈을 일정에 남겨 두면 그 인내가 성숙하게 쓰여요." }
      ],
      "aspects": [
        { "key": "Me_Sa_tr", "deviation": 0.04, "lang": "ko",
          "text": "수성과 토성의 트라인은 절제와 의지를 생각에 더해, 서두르지 않고 앞을 내다보며 구조를 짜는 데 힘이 실려요. 변화가 필요한 순간에 익숙한 방식만 고집할 수 있으니 새 방법도 한 번 시험해 보세요." },
        { "key": "Mo_Ma_sq", "deviation": 1.03, "lang": "ko",
          "text": "달과 화성이 스퀘어를 이루면 감정이 올라오는 순간 욱하거나 규칙에 반발하는 쪽으로 기울 수 있어요. 화가 난 뒤 반응을 한 템포 늦추는 연습을 하면 그 뜨거움이 지켜야 할 것을 지키는 힘으로 바뀌어요." }
      ],
      "lang": "ko",
      "costWon": 20
    }
  }
}

ข้อควรระวัง

• ราคา: ₩20 / ครั้ง (ตามการใช้งาน) · หาก readings: true เพิ่ม ₩20 (รวม ₩40)
• การตรวจสอบวันที่: วันที่ไม่ถูกต้อง (เช่น 30 กุมภาพันธ์) หรือพิกัด/เขตเวลาที่ไม่ถูกต้องจะคืนข้อผิดพลาด 400 และไม่คิดค่าบริการ
• การคำนวณลัคนา: ต้องมีเวลาเกิด + birthTimePrecision (exact/approximate หากละไว้เป็น exact) + ละติจูด/ลองจิจูดครบทั้งหมด หากขาดอย่างใดอย่างหนึ่ง ascendant จะเป็น null
• ข้อผิดพลาดของย่อหน้าการอ่าน: หาก readings: true แต่บัญชียังไม่เปิดจะได้ 404 natal_readings_not_enabled หากดึงย่อหน้าไม่ได้จะได้ 503 natal_readings_unavailable — ทั้งสองไม่คิดค่าบริการ
• ดวงอาทิตย์/ดวงจันทร์/ลัคนา: ดาวแต่ละดวงและมุมต่างๆ อิงจักรราศีแบบทรอปิคัล (มาตรฐานโหราศาสตร์ตะวันตก)
• เปลี่ยนแปลง 2026-10-17 (engineVersion natal-2): หากส่ง birthTime และละ birthTimePrecision ตอนนี้จะคำนวณด้วยเวลานั้น (เดิมละเว้นเวลาและคำนวณตามเที่ยงวัน ลัคนาจึงเป็น null) เป็นกฎเดียวกับเอนด์พอยต์อื่น การเรียกที่ไม่มี birthTime หรือส่งความแม่นยำมาเองจะได้ผลเหมือนเดิม

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

API โหราศาสตร์ตะวันตกแบบครบชุด

คืนการคำนวณโหราศาสตร์ตะวันตกทั้งหมดในการเรียกครั้งเดียวเหมือนปฏิทินหมื่นปี ค่าเริ่มต้นคือผังดวงกำเนิดเต็ม (10 ดาว ดวงอาทิตย์~พลูโต · จุดโหนดของดวงจันทร์ · 4 มุมหลัก · เรือน (ค่าเริ่มต้น Placidus) · มุมสัมพันธ์ · ศักดิ์ของดาว) และหากแนบบล็อกในคำขอ ทรานซิต + การเคลื่อนแบบ Secondary Progression (timing) และ ซินแนสทรีของสองคน (partner) จะมาในการตอบกลับเดียวกัน เลือกใช้เฉพาะส่วนที่ต้องการได้ ไม่ใช้ LLM นอกจากตัวเลขและคีย์กฎ (features) แล้ว ย่อหน้าการอ่าน (readings) ที่ HRUM เขียนไว้ล่วงหน้าจะมาด้วยเสมอโดยไม่มีค่าบริการเพิ่ม เป็นเอนจินโหราศาสตร์ตะวันตกตัวเดียวกับที่ INTA ใช้ ตำแหน่งดาวได้รับการตรวจสอบเทียบกับค่าอ้างอิงของ NASA/JPL Horizons · Swiss Ephemeris แล้ว (ดาวเคราะห์คลาดเคลื่อนไม่เกิน 0.005°) พารามิเตอร์การตีความ (ออร์บ · ชนิดมุม · ตารางศักดิ์) ทั้งหมดมาจากกฎในตำราคลาสสิก และค่าที่ตำราแต่ละเล่มเห็นต่างกัน (ออร์บของทรานซิต · โปรเกรสชัน) จะไม่มีค่าเริ่มต้นแต่ให้เลือกเอง (ดู "ค่าเริ่มต้นและค่าที่ต้องเลือกเอง" ด้านล่าง)

POST /api/v1/partners/v1/astrology

อินพุตการเกิดเหมือนกับ API ผังดวงกำเนิด (birthDate · birthTime · birthTimePrecision · birthLatitude · birthLongitude · birthTimezoneOffset ค่าเริ่มต้น 540 = KST นำเวลาออมแสงของเกาหลีและ UTC+8:30 ช่วงปี 1954~61 มาใช้อัตโนมัติ) หากละ birthTimePrecision จะเป็น unknown (อิงเที่ยงวัน)

ภายในบล็อก timing:

ตัวอย่างคำขอ 1 — พื้นฐาน (เฉพาะผังกำเนิด)

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["placidus", "whole_sign"]
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "birthTimePrecision": "exact", "birthLatitude": 37.5665, "birthLongitude": 126.978, "minorAspects": true, "lang": "en"}'

ตัวอย่างการตอบกลับ 1 (ตัดตอน ผลลัพธ์จริงของเอนจิน)

{
  "success": true,
  "data": {
    "natal": {
      "utc": "1990-05-15T05:30:00.000Z",
      "timePrecision": "exact",
      "timeKnown": true,
      "zodiac": "tropical",
      "lang": "ko",
      "bodies": [
        { "id": "Sun", "longitude": 54.1347, "sign": "Taurus", "signKey": "tau", "signName": "황소자리", "degreeInSign": 24.1347, "speed": 0.9643, "retrograde": false, "dignities": [], "house": { "placidus": 9, "whole_sign": 9 } },
        { "id": "Moon", "longitude": 293.8244, "sign": "Capricorn", "signKey": "cap", "signName": "염소자리", "degreeInSign": 23.8244, "speed": 12.2943, "retrograde": false, "dignities": ["det"], "house": { "placidus": 4, "whole_sign": 5 } },
        ...
      ],
      "nodes": [
        { "id": "MeanNode", "longitude": 311.3535, "sign": "Aquarius", "signName": "물병자리", "speed": -0.0529,
          "south": { "longitude": 131.3535, "sign": "Leo", "signName": "사자자리", ... } },
        { "id": "TrueNode", ... }
      ],
      "angles": { "asc": 173.5996, "mc": 82.8067, "dsc": 353.5996, "ic": 262.8067,
        "ascSign": { "sign": "Virgo", "signName": "처녀자리", ... }, "mcSign": { ... }, "dscSign": { ... }, "icSign": { ... }, "polar": false },
      "anglesOmitted": null,
      "houseSystems": ["placidus", "whole_sign"],
      "houses": {
        "placidus": { "cusps": [173.5996, 199.6989, 229.8749, ...], "bodies": { "Sun": 9, "Moon": 4, "Jupiter": 10, ... } },
        "whole_sign": { "cusps": [150, 180, 210, ...], "bodies": { "Sun": 9, "Moon": 5, ... } }
      },
      "housesExcluded": [],
      "orbs": "leo1928",
      "minorAspects": false,
      "aspects": [
        { "a": "Jupiter", "b": "Uranus", "type": "opposition", "code": "op", "key": "Ju_Ur_op", "separation": 179.6986, "orb": 0.3014, "orbLimit": 8, "strength": "exact", "applying": false, "outOfSign": false },
        { "a": "Sun", "b": "Moon", "type": "trine", "code": "tr", "key": "Su_Mo_tr", "orb": 0.3104, "orbLimit": 8, "strength": "exact", "applying": true, "outOfSign": false },
        ...
      ],
      "dignities": { "Sun": [], "Moon": ["det"], "Mercury": [], "Venus": ["det"], "Mars": [], "Jupiter": ["exa"], "Saturn": ["dom"] },
      "moonSignUncertain": false,
      "features": [
        { "type": "planet_sign", "key": "Su_tau" },
        { "type": "dignity", "key": "Mo_det" },
        { "type": "planet_retrograde", "key": "Me_rx" },
        { "type": "planet_house", "key": "Su_h9", "system": "placidus" },
        { "type": "aspect", "key": "Su_Mo_tr", "strength": "exact", "applying": true, "orb": 0.31 },
        { "type": "meta", "key": "time_known" },
        ...
      ]
    },
    "readings": {
      "dignities": [
        { "key": "Mo_det", "text": "달이 염소자리에서 손상 자리에 있으면 감정을 바로 내보이기보다 책임과 일의 질서 속에서 조심스럽게 다루는 경향이 있어요. ...", "lang": "ko" },
        { "key": "Ve_det", ... }, { "key": "Ju_exa", ... }, { "key": "Sa_dom", ... }
      ],
      "aspects": [
        { "key": "Su_Mo_tr", "text": "태양과 달의 트라인은 의지와 정서가 같은 곳을 바라봐, 스스로 길을 내며 생활 전반을 고르게 꾸려 가는 힘이 실려요. ...", "lang": "ko", "deviation": 0.31 },
        { "key": "Su_Sa_tr", ... }, { "key": "Mo_Sa_cj", ... }, ...
      ],
      "lang": "ko"
    },
    "readingsUnavailable": false,
    "costPoints": 50
  }
}

หากไม่ส่ง timing · partner การตอบกลับจะไม่มีคีย์ timing · synastry เลย

• bodies[]: ดวงอาทิตย์ · ดวงจันทร์ · ดาวพุธ · ดาวศุกร์ · ดาวอังคาร · ดาวพฤหัสบดี · ดาวเสาร์ · ดาวยูเรนัส · ดาวเนปจูน · ดาวพลูโต longitude คือลองจิจูดสุริยวิถี (0° = จุดวสันตวิษุวัต ทรอปิคัล) speed คือองศา/วัน — ถ้าติดลบ retrograde: true แต่ละดาวมี signName (ชื่อราศีในภาษา lang) · degreeInSign (องศาภายในราศี 0~30°) · house (หมายเลขเรือนตามระบบเรือนที่ขอ ค่าเดียวกับ houses[ระบบ].bodies — หากไม่ได้คำนวณเรือนเป็น {}) แนบอยู่ จึงวาดตารางผังได้จากข้อมูลนี้อย่างเดียว
• dignities: ศักดิ์ของดวงอาทิตย์~ดาวเสาร์ (dom เกษตร · exa อุจจ์ · det ประ · fal นิจ ทุกสถานะที่ตรง) เป็นค่าเดียวกับ bodies[].dignities
• nodes[]: MeanNode (โหนดเฉลี่ย) · TrueNode (โหนดจริง) = โหนดเหนือ, south = โหนดใต้ (+180°)
• angles: ASC · MC · DSC · IC คำนวณเฉพาะเมื่อมีทั้งเวลาเกิด (exact/approximate) และพิกัด หากไม่มีจะเป็น null และ anglesOmitted จะบอกเหตุผล (time_unknown | coordinates_missing) ในกรณีนี้จะไม่คำนวณเรือนด้วย houses จึงเป็น {}
• houses: cusps ตามระบบที่ขอ (ลองจิจูดสุริยวิถีที่เริ่มเรือน 1~12) + bodies (หมายเลขเรือนของแต่ละดาว)
• houseSystems · houses: ระบบที่คำนวณจริง ที่สถานที่เกิดในเขตขั้วโลก (angles.polar = ละติจูดประมาณ 66.56° ขึ้นไป) Placidus อาจไม่มีนิยาม จึงคำนวณแบบ Porphyry แทนแล้วแสดงด้วย houses.porphyry.fallbackFrom = "placidus" (ไม่เปลี่ยนแบบเงียบๆ) การตัดสินใช้ละติจูดของสถานที่เกิด สถานที่เกิดเดียวกันจึงได้ระบบเดิมเสมอไม่ว่าเวลาใด housesExcluded คือระบบอื่นที่คำนวณไม่ได้และเหตุผล (ไม่ใช่การตอบกลับข้อผิดพลาด)
• aspects[]: orb = องศาที่เบี่ยงจากมุมตรง strength = exact (ภายใน 2°) · close (ภายในครึ่งหนึ่งของขีดจำกัด) · wide applying = true หากกำลังเข้าหามุมตรง (ไม่ทราบเป็น null) outOfSign = มุมที่ข้ามเส้นแบ่งราศี (อ่านให้อ่อนลงหนึ่งระดับ)
• moonSignUncertain: เมื่อไม่ทราบเวลา หากราศีจันทร์เปลี่ยนภายในวันนั้นจะเป็น true — ในกรณีนี้ planet_sign ของดวงจันทร์ใน features จะมี "uncertain": true แนบมา
• readings (รวมเสมอ ไม่มีค่าบริการเพิ่ม): ย่อหน้าการอ่านที่ HRUM เขียนไว้ล่วงหน้า dignities[] = ศักดิ์ของดาว (ดวงอาทิตย์~ดาวเสาร์ ดาวละหนึ่งสถานะที่แรงที่สุด) aspects[] = มุมระหว่างดาวกำเนิด เรียงตามออร์บจากแคบไปกว้าง แต่ละย่อหน้ามี key (คีย์เดียวกับ features · aspects[].key) · text · lang (ภาษาจริงของย่อหน้า — หากไม่มีย่อหน้าในภาษาที่ขอเป็น ko) · deviation (เฉพาะมุม องศาที่เบี่ยงจากมุมตรง) แนบเฉพาะคีย์ที่มีย่อหน้าเขียนไว้ล่วงหน้า ที่เหลือจะข้าม (ไม่แต่งขึ้นทันที) — มุมที่มีดาวยูเรนัส · เนปจูน · พลูโตเกี่ยวข้องและมุมรองไม่มีย่อหน้าจึงไม่รวม หากไม่มีเวลาเกิด มุมที่มีดวงจันทร์เกี่ยวข้องจะไม่แนบ และหากราศีจันทร์ไม่แน่นอน ศักดิ์ของดวงจันทร์จะไม่แนบ ตัวอย่างข้างต้น (1990-05-15 14:30 โซล) คือ มุมสัมพันธ์ 7 จาก 16 รายการ + ศักดิ์ 4 รายการ = 11 ย่อหน้า
• readingsUnavailable: เป็น true เมื่อดึงย่อหน้าการอ่านไม่ได้ — ในกรณีนี้ผลการคำนวณผังยังมาตามเดิม readings เป็นอาร์เรย์ว่าง และราคา (₩50) ก็เท่าเดิม
• features[]: คีย์สำหรับจับคู่กับ DB กฎ planet_sign Su_ari · planet_retrograde Me_rx · dignity Ma_dom · node_sign MNn_leo · TNn_leo · Nn_leo · Sn_aqu (Nn · Sn คือโหนดตามตัวเลือก node) · angle_sign Asc_sco · planet_house Ve_h7 (+system) · aspect Su_Mo_cj (โหนดมีเฉพาะการกุม 3° — Mo_Nn_cj · Sa_Sn_cj · Nn_Asc_cj คู่ที่มีลัคนาเฉพาะเมื่อมีเวลาเกิด) · house_cusp_sign h12_ari (คัสป์เรือน 12 อยู่ราศีเมษ) · house_empty h6 (เรือนที่ไม่มีดาวเคราะห์ใดใน 10 ดวงเลย) · house_ruler_house h1_h7 (เจ้าเรือน 1 อยู่เรือน 7) · house_ruler_sign h7_lib (เจ้าเรือน 7 อยู่ราศีตุลย์) — เจ้าเรือนคือเจ้าราศีแบบดั้งเดิมของราศีคัสป์ (7 ดาว ดวงอาทิตย์~ดาวเสาร์) · planet_rising Ju (เรือน 1 หรืออยู่ในเรือน 12 ภายใน 6° จากลัคนา) — ห้าประเภทนี้มี +system และมีเฉพาะเมื่อมีเวลาเกิดและพิกัด · planet_solar Ve_cazimi (ภายใน 17′ จากดวงอาทิตย์) / Me_combust (17′~8°30′ ราศีเดียวกับดวงอาทิตย์) / Ma_beams (นอกนั้นภายใน 17°) — สามระดับไม่ซ้อนกัน · moon_phase waxing · waning · meta time_known (มีเวลา — exact · approximate) / time_hour_level (เพิ่มเมื่อเป็น approximate) / time_unknown แต่ละคีย์ (aspect · transit · progressed · syn_aspect) จะมี orb (องศาที่เบี่ยงจากมุมตรง ทศนิยม 2 ตำแหน่ง) และ "outOfSign": true เฉพาะเมื่อมุมข้ามเส้นแบ่งราศี — เป็นค่าที่ใช้จับคู่กับแอตทริบิวต์ของคีย์กฎ [orb=…] · [outOfSign=true] หากไม่ทราบเวลาเกิด มุมกำเนิดที่มีดวงจันทร์เกี่ยวข้องจะมี "uncertain": true แนบมา ตัวย่อดาว Su Mo Me Ve Ma Ju Sa Ur Ne Pl โหนด MNn TNn Nn Sn รหัสมุม cj (0°) sx (60°) sq (90°) tr (120°) op (180°) · มุมรอง ssx (30°) ssq (45°) sqq (135°) qcx (150°)

ตัวอย่างคำขอ 2 — รวม timing (ทรานซิต + Secondary Progression)

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["whole_sign"],
  "timing": { "at": "2026-10-11T09:00:00+09:00", "orbDegrees": 3, "yearLength": "tropical" }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "timing": {"orbDegrees": 2, "progressions": false}}'

ตัวอย่างการตอบกลับ 2 (ตัดตอน natal มีรูปแบบเดียวกับตัวอย่าง 1)

{
  "success": true,
  "data": {
    "natal": { ... },
    "timing": {
      "at": "2026-10-11T00:00:00.000Z",
      "orbDegrees": 3,
      "natalPoints": ["Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto", "Asc", "MC"],
      "transits": {
        "bodies": [ { "id": "Sun", "longitude": 197.6966, "sign": "Libra", "signName": "천칭자리", "speed": 0.9889, "retrograde": false, ... }, ... ],
        "aspects": [
          { "a": "Mars", "b": "Mercury", "type": "square", "key": "tMa_nMe_sq", "orb": 0.6358, "orbLimit": 3, "strength": "exact", "applying": true, "outOfSign": false },
          ...
        ]
      },
      "progressions": {
        "yearLength": "tropical",
        "yearLengthDays": 365.24219,
        "ageYears": 36.4081,
        "instant": "1990-06-20T15:17:39.048Z",
        "bodies": [ { "id": "Sun", "longitude": 89.0352, "sign": "Gemini", "signName": "쌍둥이자리", ... }, ... ],
        "aspects": [
          { "a": "Uranus", "b": "Mercury", "type": "trine", "key": "pUr_nMe_tr", "orb": 0.0862, "orbLimit": 3, "strength": "exact", "applying": false, "outOfSign": false },
          ...
        ]
      },
      "features": [
        { "type": "transit", "key": "tMa_nMe_sq", "strength": "exact", "applying": true, "orb": 0.64 },
        { "type": "progressed", "key": "pUr_nMe_tr", "strength": "exact", "applying": false, "orb": 0.09 },
        ...
      ]
    },
    "readings": { ... }, "readingsUnavailable": false,
    "costPoints": 50
  }
}

• เป้าหมายทรานซิต (natalPoints): ดาวกำเนิด 10 ดวง + ลัคนา (Asc) · กลางฟ้า (MC) หากมีเวลาเกิด · พิกัด คีย์มีคำนำหน้า t (ทรานซิต) · n (กำเนิด) — tSa_nSu_cj = ดาวเสาร์ทรานซิตกุมดวงอาทิตย์กำเนิด
• transit_house tSa_h7 (ดาวเสาร์ทรานซิตอยู่เรือน 7 กำเนิด) · progressed_house pMo_h4 (ดวงจันทร์โปรเกรสอยู่เรือน 4 กำเนิด): ดาวเคราะห์อย่างละ 10 ดวง เรือนกำเนิดใช้ระบบเริ่มต้น (Placidus หากเป็นเขตขั้วโลกใช้ Porphyry + "fallbackFrom": "placidus") และคีย์จะมี "system" แนบมา — แม้ส่ง houseSystems ต่างไป สองคีย์นี้ก็อิงระบบเริ่มต้น หากไม่มีเวลาเกิดหรือพิกัดจะไม่ออกมา
• มุมโปรเกรส→กำเนิดมีเป้าหมายเฉพาะดาวเคราะห์กำเนิด คีย์ pSu_nJu_tr = ดวงอาทิตย์โปรเกรสทำมุมไตรน์กับดาวพฤหัสบดีกำเนิด instant คือเวลาของท้องฟ้าที่ใช้เป็นผังโปรเกรส (เวลาเกิด + ageYears วัน)
• หาก progressions: false timing.progressions จะเป็น null หากละ yearLength จะเป็น tropical (365.24219 วัน)
• เมื่อเปิด progressions อยู่ หาก timing.at มาก่อนเวลาเกิดจะได้ 400 at_before_birth (ไม่คิดค่าบริการ)
• หากไม่ทราบเวลา จะตั้งผังกำเนิดตามเที่ยงวัน คีย์ที่มีเป้าหมายเป็นดวงจันทร์กำเนิด (…_nMo_…) และคีย์ดวงจันทร์โปรเกรส (pMo_…) จะมี "uncertain": true แนบมา (ดวงจันทร์โปรเกรสรับตำแหน่งดวงจันทร์กำเนิดมาตามเดิม จึงแกว่งเท่ากับเกณฑ์เที่ยงวัน)

ตัวอย่างคำขอ 3 — รวม partner (ซินแนสทรี)

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "birthTimePrecision": "exact",
  "birthLatitude": 37.5665,
  "birthLongitude": 126.978,
  "houseSystems": ["whole_sign"],
  "partner": { "birthDate": "1992-11-03", "birthTime": "08:10", "birthTimePrecision": "exact", "birthLatitude": 35.1796, "birthLongitude": 129.0756 }
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/astrology \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "birthTimePrecision": "exact", "partner": {"birthDate": "1992-11-03"}}'

ตัวอย่างการตอบกลับ 3 (ตัดตอน natal มีรูปแบบเดียวกับตัวอย่าง 1)

{
  "success": true,
  "data": {
    "natal": { ... },
    "synastry": {
      "partner": {
        "utc": "1992-11-02T23:10:00.000Z",
        "timePrecision": "exact",
        "timeKnown": true,
        "moonSignUncertain": false,
        "bodies": [ { "id": "Sun", "longitude": 220.7903, "sign": "Scorpio", "signName": "전갈자리", "speed": 1.0016, "retrograde": false, "dignities": [], ... }, ... ],
        "angles": { "asc": 252.31, "mc": 175.86, "ascSign": { "sign": "Sagittarius", "signName": "사수자리", ... }, "mcSign": { "sign": "Virgo", "signName": "처녀자리", ... } },
        "anglesOmitted": null
      },
      "orbs": "leo1928",
      "minorAspects": false,
      "aspects": [
        { "a": "Moon", "b": "Mars", "type": "opposition", "code": "op", "key": "aMo_bMa_op", "orb": 0.2993, "orbLimit": 10, "strength": "exact", "applying": null, "outOfSign": false },
        { "a": "Neptune", "b": "Uranus", "type": "conjunction", "code": "cj", "key": "aNe_bUr_cj", "orb": 0.3898, "orbLimit": 8, "strength": "exact", "applying": null, "outOfSign": false },
        ...
      ],
      "features": [
        { "type": "syn_aspect", "key": "aMo_bMa_op", "strength": "exact", "orb": 0.3 },
        { "type": "syn_aspect", "key": "aNe_bUr_cj", "strength": "exact", "orb": 0.39 },
        { "type": "astro_syn", "key": "Su_Mo_se" },
        { "type": "syn_sign", "key": "aAsc_bAsc_es" },
        ...
      ]
    },
    "readings": { ... }, "readingsUnavailable": false,
    "costPoints": 50
  }
}

• คำนำหน้าคีย์ a = ผู้ขอเอง b = partner aVe_bMa_cj = ดาวศุกร์ของตัวเองกุมดาวอังคารของอีกฝ่าย ดูครบทุกคู่ระหว่างดาวของตัวเอง 10 ดวง (+ลัคนา · กลางฟ้า) × ดาวของอีกฝ่าย 10 ดวง (+ลัคนา · กลางฟ้า) (มีทิศทาง aSu_bMo กับ aMo_bSu จึงเป็นคนละคีย์)
• ลัคนา (Asc) · กลางฟ้า (MC) คำนวณเฉพาะเมื่อบุคคลนั้นมีทั้งเวลาเกิดและพิกัด (กฎเดียวกับตัวเอง ของอีกฝ่ายอยู่ที่ synastry.partner.angles/anglesOmitted) มุมไขว้ที่มีมุมหลักเกี่ยวข้องดูเฉพาะการกุม · เล็ง 6° แต่เฉพาะการกุมระหว่างลัคนาด้วยกัน (aAsc_bAsc_cj) ให้ถึง 17° (ปโตเลมี "Tetrabiblos" — หากลัคนาสองคนอยู่ภายใน 17° ความผูกพันจะแข็งแรง กฎ [orb=17]) องศาที่ห่างจริงมาใน orb มุมหลักจะคำนวณเมื่อเวลาของผู้ที่มีมุมนั้นแน่นอนเท่านั้น จุดตก · ก้นฟ้าเป็นด้านตรงข้ามของลัคนา · กลางฟ้า จึงไม่ออกคีย์แยก
• astro_syn: ความสัมพันธ์ราศีที่แรงที่สุด 2 รายการ จาก 6 คู่คลาสสิก (ดวงอาทิตย์–ดวงจันทร์ ดาวศุกร์–ดาวอังคาร ดวงจันทร์–ดาวศุกร์ ดวงอาทิตย์–ดาวศุกร์ ดวงจันทร์–ดาวอังคาร ดาวศุกร์–ดาวเสาร์) รวมสองทิศทางเป็นคีย์เดียว (Su_Mo_se = ดวงอาทิตย์ของฝ่ายหนึ่งกับดวงจันทร์ของอีกฝ่ายเป็นธาตุเดียวกัน) syn_sign: ความสัมพันธ์ราศีของทุกคู่จุดของตัวเอง × จุดของอีกฝ่าย (aAsc_bAsc_ss) หากทั้งสองคนมีเวลาเกิดเป็น exact จะรวมจุดโชคลาภ (PoF สลับสูตรกลางวัน/กลางคืน) เป็นจุดด้วย (aPoF_bPoF_ss) — จุดโชคลาภเคลื่อนไปพร้อมลัคนาประมาณ 1° ทุก 4 นาที จึงไม่ออกในระดับชั่วโมง (approximate) หรือเมื่อไม่ทราบเวลา รหัสความสัมพันธ์ ss (ราศีเดียวกัน) · op (ตรงข้าม) · se (ธาตุเดียวกัน) · es (ธาตุเกื้อหนุน) · sm (ลักษณะเดียวกัน) · ef (ธาตุเสียดทาน) · nt (ไม่เกี่ยวข้อง)
• ตารางออร์บและการรวมมุมรองใช้ orbs · minorAspects เดียวกับผังกำเนิด เป็นมุมระหว่างผังกำเนิดสองผังจึงไม่มีการเข้าหา · แยกจาก applying จึงเป็น null เสมอ
• หากฝ่ายใดฝ่ายหนึ่งไม่ทราบเวลาเกิด ผังของคนนั้นจะอิงเที่ยงวัน มุมที่มีดวงจันทร์ของคนนั้นเกี่ยวข้องจะมี "uncertain": true ใน features (ดวงจันทร์เคลื่อนวันละประมาณ 13° จึงแกว่งกว้างกว่าออร์บ) มุมที่จับคู่กับมุมหลักของอีกฝ่าย (aAsc_bMo_… ทิศทางกลับ aMo_bAsc_…) ก็เช่นกัน
• ไม่คำนวณเรือนของอีกฝ่าย (ไม่มีการซ้อนเรือนของซินแนสทรี)

ค่าเริ่มต้นและค่าที่ต้องเลือกเอง

• ระบบเรือน (ค่าเริ่มต้น placidus): ระบบที่พจนานุกรมปี 1819 · 1929 ระบุว่า "ใช้กันทั่วไป" ที่สถานที่เกิดในเขตขั้วโลกจะใช้ Porphyry แทนและแสดงด้วย fallbackFrom หากต้องการระบบอื่นให้เลือกด้วย houseSystems
• ความยาว 1 ปีของโปรเกรสชัน (ค่าเริ่มต้น tropical 365.24219 วัน): 1 ปีแบบ "วันเกิด→วันเกิดถัดไป" ตามตำรา ความต่างกับปีจูเลียน (julian) คือเวลาโปรเกรสประมาณ 2.5 นาทีเมื่ออายุ 80 ปี
• ออร์บของทรานซิต · โปรเกรสชัน (timing.orbDegrees จำเป็นเมื่อส่ง timing): ตำราแต่ละเล่มต่างกัน (ช่วงก่อนมุมตรง 8° กับ 10°) หากเว้นว่างจะได้ 400
• มุมกำเนิดที่มีดาวพลูโต · โหนด · มุมหลักเกี่ยวข้องไม่อยู่ในตารางออร์บเริ่มต้น: เป็นจุดที่ตารางออร์บของ Leo (1928) · Heindel (1919) ไม่ได้ครอบคลุม (ดาวพลูโตค้นพบในปี 1930) ดังนั้น aspects ของผังกำเนิดจึงไม่มีจุดเหล่านี้ (แต่มีในตำแหน่ง · เรือน) เฉพาะมุมไขว้ของมุมหลักในซินแนสทรีที่ดูการกุม · เล็ง 6° (เฉพาะการกุมระหว่างลัคนา 17°)

สิ่งที่ไม่ได้ให้บริการ

• ศักดิ์รอง (ตรีภาค · เขต term · หน้า face) การรับกัน (reception) จุดโชคลาภของผังกำเนิด (ใช้เฉพาะใน syn_sign ของซินแนสทรี) ศักดิ์ของดาวยูเรนัส · เนปจูน · พลูโต พาราเลล · จุดกึ่งกลาง
• มุมหลักแบบโปรเกรส (ASC · MC โปรเกรส) — ตำราไม่ได้กำหนดวิธีไว้
• DSC · IC ให้ค่า แต่ไม่ออกคีย์ features (โหนดใต้ออกเป็นคีย์ Sn)
• คีย์ข้างขึ้นข้างแรมแบบเดือนดับ · เพ็ญ · ขึ้นครึ่งดวง · แรมครึ่งดวง (moon_phase มีเฉพาะ waxing · waning) ดวงอาทิตย์ตะวันออก · ตะวันตก (oriental · occidental) คีย์มุมหลักแบบโปรเกรส
• การซ้อนเรือนของซินแนสทรี

ราคา

• ₩50 ต่อครั้งเท่ากับปฏิทินหมื่นปี — แม้เพิ่มบล็อก timing · partner และไม่ว่าระบบเรือน · การรวมมุมรองจะเป็นอย่างไร ก็ ₩50 ครั้งเดียวเหมือนเดิม costPoints ในการตอบกลับคือยอดที่หักครั้งนี้ (₩) endpoint ในบันทึกการใช้งานคือ astrology
• หักเฉพาะเมื่อคำนวณสำเร็จ อินพุตผิดพลาด (400) · ยอดคงเหลือไม่พอ (402) ไม่คิดค่าบริการ
• หากเรียกขณะที่ยังไม่เปิด จะได้ 404 astrology_not_enabled (ไม่คิดค่าบริการ)

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

API กราฟดวงชะตา

คำนวณกระแสที่วัยจร 10 ปี · ดวงรายปี · ดวงรายเดือนซ้อนทับบนผังดวงจากซาจูของบุคคลหนึ่ง แล้วคืนเป็นตัวเลขสำหรับกราฟและรายการความสัมพันธ์ ครั้งละหนึ่งคน ไม่ใช้ LLM ค่าแกนตั้งคือ"คะแนนฝั่งก้านวันเกิดเมื่อซ้อนอักษรของดวงจร" — นำคะแนนรวมความแข็ง-อ่อนของผังดวงมาบวกส่วนที่ให้คะแนนอักษรดวงจรแต่ละตัวด้วยตารางคะแนนต่ออักษรเดียวกับผังดวง (เกื้อหนุน · ควบคุม · ก้านแฝง · ราก) แล้วตัดที่ ±100 ไม่ได้วัดความดีร้ายของดวง (R-SAJU-UN-034) ชื่อดวงแข็ง · สมดุล · ดวงอ่อนใช้ตามผังดวงเดิม และไม่ตั้งใหม่ตามดวงจร

ราคา: ₩50 ต่อครั้ง (เท่ากับปฏิทินหมื่นปี ขยายช่วง · ดวงรายเดือนก็ราคาเดิม) การตอบกลับที่ล้มเหลวอย่าง 400 ไม่คิดค่าบริการ

ตัวเลขทั้งหมดเป็นค่าจากเอนจินซาจูกลางตัวเดียวกับ INTA เวลาเกิดอ่านเป็นนาฬิกาตามประวัติเวลามาตรฐานเกาหลี (1954~61 UTC+8:30 นำเวลาออมแสงมาใช้อัตโนมัติ) แล้วเทียบกับจุดเปลี่ยนฤดู จึงได้ผลเดียวกันไม่ว่าเขตเวลาของเซิร์ฟเวอร์จะเป็นอะไร

สถานที่เกิด (เพิ่มเมื่อ 2026-10-15 saju-flow-5): รับฟิลด์เดียวกับ API ปฏิทินหมื่นปี (birthLatitude · birthLongitude · country · birthTimePrecision) และปรับเวลาสุริยะจริงด้วยวิธีเดียวกัน หากเวลาเกิดอยู่ใกล้เส้นแบ่งเสายาม · เสาวัน · จุดเปลี่ยนฤดู การปรับจะเปลี่ยนอักษรของผังดวง จึงต้องส่งตำแหน่งที่ส่งให้ปฏิทินหมื่นปีมาที่กราฟดวงชะตาด้วยตามเดิม ผลทั้งสองจึงจะใช้ผังดวงเดียวกัน หากไม่ส่งตำแหน่ง จะคำนวณด้วยการจัดการเริ่มต้นเดียวกับเมื่อเรียกปฏิทินหมื่นปีโดยไม่มีตำแหน่ง (ตอนนี้ไม่ปรับ) และแจ้งค่าเริ่มต้นนั้นใน assumedLocation ของการตอบกลับ

POST /api/v1/partners/v1/saju-flow

ตัวอย่างคำขอ

{
  "birthDate": "1990-05-15",
  "birthTime": "14:30",
  "calendar": "solar",
  "gender": "male",
  "timezone": "Asia/Seoul",
  "range": { "fromYear": 1990, "toYear": 2090 },
  "monthsOfYear": 2026
}

curl -X POST https://api.hrum.ai/api/v1/partners/v1/saju-flow \
  -H "X-Partner-Api-Key: $HRUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: chart-123:flow:2026" \
  -d '{"birthDate": "1990-05-15", "birthTime": "14:30", "calendar": "solar", "gender": "male", "timezone": "Asia/Seoul", "range": {"fromYear": 1990, "toYear": 2090}, "monthsOfYear": 2026}'

ตัวอย่างการตอบกลับ (ตัดตอน ผลลัพธ์จริงของเอนจิน)

{
  "success": true,
  "data": {
    "engineVersion": "saju-flow-6",
    "kbVersion": "2026.10.11-7",
    "hourKnown": true,
    "natalAmbiguous": null,
    "natal": {
      "score": -37, "result": "중화", "level": "약약",
      "breakdown": { "season": -30, "support": 36, "control": -28, "hidden": -5, "root": 5 },
      "primaryYongshin": "토",
      "shin": { "yongshin": "토", "huishin": "화", "gishin": "목", "gushin": "수", "hanshin": "금" },
      "ruleIds": ["R-SAJU-STR-001", "R-SAJU-STR-018", "R-SAJU-STR-019", "R-SAJU-YONG-170"]
    },
    "daeun": [
      { "startYear": 1997, "endYear": 2006, "startAge": 7,
        "chars": [
          { "pos": "stem", "char": "임", "hanja": "壬", "ohaeng": "수", "sipsin": "식신", "shinRole": "gushin",
            "share": { "support": 0, "control": -8, "hidden": 0, "root": 0, "total": -8 } },
          { "pos": "branch", "char": "오", "hanja": "午", "ohaeng": "화", "sipsin": "정관", "shinRole": "huishin",
            "share": { "support": 0, "control": -10, "hidden": -5, "root": 0, "total": -15 } }
        ],
        "delta": -23, "line": { "value": -60, "clamped": false },
        "relations": [
          { "type": "자형", "from": "daeun", "with": "yearBranch", "a": "오", "b": "오", "ruleId": "R-SAJU-REL-044", "decisionRuleId": "R-SAJU-UN-036" },
          { "type": "육합", "from": "daeun", "with": "hourBranch", "a": "오", "b": "미", "ruleId": "R-SAJU-REL-015", "decisionRuleId": null }
        ],
        "triples": [], "hapPulim": [ ... ] },
      ...
    ],
    "years": [
      { "year": 2026, "daeunIndex": 2,
        "chars": [ { "pos": "stem", "char": "병", "hanja": "丙", ... "share": { ..., "total": -10 } },
                   { "pos": "branch", "char": "오", "hanja": "午", ... "share": { ..., "total": -15 } } ],
        "delta": -25, "line": { "value": -33, "clamped": false },
        "relations": [
          { "type": "천간합", "from": "seun", "with": "monthStem", "a": "병", "b": "신", "ruleId": "R-SAJU-REL-003", "decisionRuleId": null },
          ...
        ],
        "withDaeun": [], "triples": [],
        "hapPulim": [
          { "kind": "existing", "domain": "jiji", "pair": ["오", "미"], "status": "broken_by_dong",
            "reasonCode": "branch_hap_broken", "params": { "incoming": "오", "origin": "seun" },
            "triggeredBy": { "origin": "seun", "value": "오" },
            "reasonFallback": "동기 오(seun) 도래 → 합반 깨짐" },
          { "kind": "new", "domain": "cheongan", "pair": ["병", "신"], "chartValue": "신", "incomingValue": "병", "incomingOrigin": "seun",
            "reasonCode": "new_stem_hap", "params": { "incoming": "병", "origin": "seun", "partner": "신" },
            "reasonFallback": "병(seun) + 원국 신 → 새 천간 합 형성" },
          ...
        ],
        "ipchunNote": false },
      ...
    ],
    "months": [
      { "index": 1, "startsAt": "2026-02-04T04:55:00+09:00",
        "chars": [ { "pos": "stem", "char": "경", ... }, { "pos": "branch", "char": "인", ... } ],
        "delta": 4,
        "relations": [ { "type": "반합", "from": "wolun", "with": "yearBranch", "a": "인", "b": "오", "ruleId": "R-SAJU-REL-024", "decisionRuleId": "R-SAJU-UN-035" }, ... ] },
      ...
    ],
    "compatInputs": {
      "primaryYongshin": "토",
      "surfaceElementCounts": { "목": 0, "화": 2, "토": 2, "금": 3, "수": 1 },
      "surfaceAbsent": ["목"],
      "hourKnown": true,
      "ruleIds": ["R-SAJU-COMPAT-008", "R-SAJU-COMPAT-009", "R-SAJU-COMPAT-010"]
    },
    "caveats": ["R-SAJU-UN-028", "R-SAJU-PRAC-026", "R-SAJU-UN-034"],
    "birthBeforeIpchun": false,
    "assumedLocation": { "correction": "none" },
    "costPoints": 0
  }
}

วิธีอ่านฟิลด์

• line: ค่าสะสม — วัยจร 10 ปีคือผังดวง + วัยจร 10 ปี ดวงรายปีคือผังดวง + วัยจร 10 ปีของปีนั้น + ดวงรายปี ทุกขั้นตัดที่ ±100 และถ้าถูกตัดจะเป็น clamped: true (R-SAJU-UN-033) ดวงรายเดือนไม่มีเส้นสะสม ให้เฉพาะส่วนของดวงเดือนนั้น (delta)
• share: การแยกส่วนของอักษรหนึ่งตัว (เกื้อหนุน · ควบคุม · ก้านแฝง · ราก) น้ำหนักของชั้นวัยจร 10 ปี · ดวงรายปี · ดวงรายเดือนเป็น 1:1:1 (R-SAJU-UN-030) รากของกิ่งดินดวงจรไม่มีเพดาน (R-SAJU-UN-031)
• shinRole: ชื่อ 5 ธาตุ (ธาตุช่วย · ธาตุยินดี · ธาตุต้องห้าม · ธาตุศัตรู · ธาตุว่าง R-SAJU-YONG-170) ของธาตุของอักษรนั้น — เป็นชื่อ ไม่ใช่คะแนน ทุกผังดวงจะมีตาราง 5 ธาตุ (ไม่มี null)
• relations: รายการลงโทษ · ปะทะ · ประชุม · รวม ระหว่างอักษรดวงจรกับอักษรผังดวง (ไม่นำมาคิดคะแนน) ruleId คือกฎตารางคู่ decisionRuleId คือกฎหลักฐานที่ใช้กับดวงจรด้วย (UN-035 ดวงรายเดือน UN-036 ลงโทษตัวเอง UN-037 รวมครึ่ง) withDaeun คือดวงรายปี ↔ วัยจร 10 ปีของปีนั้น หากไม่ทราบเสายามจะไม่ออกความสัมพันธ์กับเสายาม
• triples: กรณีที่อักษรวัยจร 10 ปี · ดวงรายปีเข้ามาแล้วครบสามอักษรของรวมสาม · รวมทิศร่วมกับผังดวง (R-SAJU-UN-037)
• hapPulim: การรวมในผังดวงที่อักษรวัยจร 10 ปี · ดวงรายปีไปกระทบ (การรวมถูกกระตุ้น · คลาย · แตก) และการรวมที่เกิดใหม่ (R-SAJU-HAP-021~027) ไม่รวมดวงรายเดือน ข้อความบนหน้าจอให้สร้างเองตามภาษาของแอปจาก reasonCode และ params (incoming อักษรดวงจรที่เข้ามา origin daeun|seun และ target · partner เมื่อจำเป็น) reasonFallback คือประโยคภาษาเกาหลีที่เอนจินเขียนไว้ซึ่งมีอยู่เสมอ ใช้แสดงแทนเฉพาะเมื่อได้ reasonCode ที่แอปไม่รู้จัก ตอนนี้ reasonCode มี 7 แบบ
  • stem_hap_kept_jaenghap: การรวมก้านฟ้าในผังดวงคงอยู่ และอักษรดวงจรที่เป็นก้านหยางตัวเดียวกัน (incoming) เป็นการแย่งรวม (jaenghap) จึงแทรกไม่ได้
  • stem_hap_kept_tuhap: การรวมก้านฟ้าในผังดวงคงอยู่ และอักษรดวงจรที่เป็นก้านหยินตัวเดียวกัน (incoming) เป็นการหึงรวม (tuhap) จึงแทรกไม่ได้
  • branch_hap_gi: อักษรดวงจร (incoming) ปะทะอักษรหนึ่ง (target) ของการรวมหกในผังดวง ทำให้การรวมถูกกระตุ้น (hapgi)
  • branch_hap_released: อักษรดวงจร (incoming) ลงโทษอักษรหนึ่งของการรวมหกในผังดวง ทำให้การรวมคลาย
  • branch_hap_broken: อักษรเดียวกับอักษรหนึ่งของการรวมหกในผังดวง (incoming) เข้ามาเป็นดวงจร ทำให้การรวมแตก
  • new_stem_hap: ก้านฟ้าดวงจร (incoming) กับก้านฟ้าว่างในผังดวง (partner) เกิดการรวมก้านฟ้าใหม่
  • new_branch_yukhap: กิ่งดินดวงจร (incoming) กับกิ่งดินผังดวง (partner) เกิดการรวมหกใหม่
• startAge: เลขวัยจร (อายุวัยจรแรก) นับจำนวนวันตั้งแต่ 0 นาฬิกาของวันเกิด (วันที่เกาหลี) ถึงจุดเปลี่ยนฤดู ไม่รวมชั่วโมง · นาทีที่เกิด และปัดเศษโดย 3 วัน = 1 ปี (R-SAJU-UN-038) เป็นกฎที่อยู่ในบัญชีหลักตั้งแต่ kbVersion 2026.10.11-2
• ipchunNote: หากเวลาที่ดึงข้อมูล (เวลาเกาหลี) อยู่ก่อนลี่ชุนของปีนั้น จะเป็น true เฉพาะช่องของปีนี้ เป็นเครื่องหมายว่าช่วง 1 มกราคม~ก่อนลี่ชุน ดวงรายปีของปีก่อนยังดำเนินอยู่ ดวงรายปีคือก้าน-กิ่งของลี่ชุนปีนั้น (R-SAJU-UN-016)
• birthBeforeIpchun: true หากเกิดช่วง 1 มกราคม~ก่อนลี่ชุน ทำให้เสาปีของผังดวงเป็นก้าน-กิ่งของปีก่อน (ฟิลด์ระดับบนสุด)
• assumedLocation (ตั้งแต่ saju-flow-5 ฟิลด์ระดับบนสุด): ค่าเริ่มต้นที่ใช้คำนวณเมื่อไม่ได้ส่งตำแหน่ง ตอนนี้เหมือนปฏิทินหมื่นปีคือ { "correction": "none" } (ไม่ปรับเวลาสุริยะจริง) หากค่าเริ่มต้นของปฏิทินหมื่นปีเปลี่ยนเป็นลองจิจูดตัวแทน จะได้ { "correction": "trueSolarTime", "longitude": … } หากส่งตำแหน่ง (birthLatitude · birthLongitude หรือ country) จะเป็น null
• natalAmbiguous: หากไม่ทราบเวลาแต่วันเกิดมีจุดเปลี่ยนฤดู จะเป็น { "pillar": "month" | "year", "termAt" } — เอนจินตัดสินตามเที่ยงวัน จึงเป็นเครื่องหมายว่าเสาเดือน (หากเป็นลี่ชุนรวมถึงเสาปี) อาจต่างจากความจริง
• compatInputs: ค่าที่ให้แอปทำเพียงหาส่วนร่วมของเซตเมื่อดูหลายคนซ้อนกัน (ธาตุของธาตุช่วย จำนวนธาตุของอักษรที่ปรากฏ ธาตุที่ไม่ปรากฏ) ไม่สร้างผลรวม · อันดับระหว่างบุคคล

ราคา

• หากปิดการขายอยู่ จะคืน 404 saju_flow_not_enabled (ไม่คิดค่าบริการ)
• หักเฉพาะเมื่อคำนวณสำเร็จ อินพุตผิดพลาด (400 — วันที่ไม่มีอยู่จริง ช่วงเกิน 101 ปี ฯลฯ) และ 409 ไม่คิดค่าบริการ costPoints ในการตอบกลับคือยอดที่หักครั้งนี้ (₩) endpoint ในบันทึกการใช้งานคือ saju-flow

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

API ดวงสมพงษ์

คำนวณดวงสมพงษ์จากซาจูของสองคน คืนดวงสมพงษ์ซาจู (ตารางดวงสมพงษ์เสาวัน 60×60 · คะแนนตามวัตถุประสงค์และ 6 แกน · ความสัมพันธ์ก้านฟ้า/กิ่งดิน · การเติมธาตุทั้งห้าของ 8 อักษร · สิบเทพ · ดาวพิเศษไขว้) ตารางสัญลักษณ์ความเข้ากันลึก (สัญลักษณ์ · ระดับจากตารางเสาวันชาย-หญิงของเอกสารอ้างอิง (1995)) ดวงสมพงษ์ราศี (3 ชั้น ดวงอาทิตย์ · ดวงจันทร์ · ลัคนา + ดาวตามวัตถุประสงค์ ย่อหน้าดวงสมพงษ์ราศีสูงสุด 2 ย่อหน้า) และดวงสมพงษ์ปีนักษัตร (ความสัมพันธ์กิ่งดินของปีนักษัตรทั้งสองและระดับ) ในครั้งเดียว พร้อมคะแนนรวม (headerBreakdown) ที่รวมคะแนนทั้งห้าด้วยน้ำหนักตามวัตถุประสงค์ ตั้งแต่ 2026-10-16 ยังมีตารางความสัมพันธ์ (relations) ที่รวบรวมการรวม · ปะทะ · ลงโทษ · ทำร้าย · ทำลาย ฯลฯ ระหว่างผังดวงทั้งสองแยกตามตำแหน่ง และคะแนนของตาราง (p2Score) มาด้วย เป็นเอนจินเดียวกับหน้าจอดวงสมพงษ์ของแอป INTA และอินพุตเดียวกันให้ผลเดียวกันเสมอ

คะแนนหลัก (ตัวเลขใหญ่) บนหน้าจอแอป INTA = headerBreakdown.average (62 ในตัวอย่างการตอบกลับด้านล่าง) saju.score.total (59 ในตัวอย่าง) เป็นคะแนนเฉพาะของ HRUM ที่เฉลี่ยเพียงตารางเสาวัน · 8 อักษร จึงต่างจากตัวเลขบนหน้าจอ

ค่าที่ตรงกับกราฟ 6 แกนบนหน้าจอผลลัพธ์ของแอป INTA คือ saju.iljuAxes (saju.axes เป็นค่าอื่นที่คำนวณใหม่ตามวัตถุประสงค์) ผู้ที่ทราบเวลาเกิดต้องส่ง personXCountry + personXBirthTimePrecision: "exact" ด้วยกันเหมือนการเรียกที่แนะนำ จึงจะคำนวณด้วยซาจูเดียวกับแอป INTA (ปรับเวลาสุริยะจริง)

POST /api/v1/partners/v1/compat

วิเคราะห์ดวงสมพงษ์จากซาจูของสองคน

พารามิเตอร์คำขอ

ตัวเลือก details · flow · MBTI ไม่มีค่าบริการเพิ่ม (ยังเป็น ₩20 ต่อครั้งเหมือนเดิม)

• การปรับเวลา: ซาจูของแต่ละคน (เสาวัน · คะแนน 8 อักษร · คะแนนรวม · ตารางสัญลักษณ์ความเข้ากันลึก · ปีนักษัตร · การวิเคราะห์ตามผู้เชี่ยวชาญ · yearFlow · คำบรรยายความสัมพันธ์) จะคำนวณครั้งเดียวแล้วใช้ร่วมกันทุกรายการ หากไม่ส่งพิกัด · personXCountry · ความแม่นยำ exact จะคำนวณตามเวลาที่ป้อนเลย (เหมือน API ปฏิทินหมื่นปี) หากต้องการดวงสมพงษ์เดียวกับแอป INTA (ภาษาเกาหลี ป้อนเวลาเอง) ให้ส่ง personXCountry: "KR" (+ personXBirthTimePrecision: "exact") ทั้งสองคน — ดูการเรียกที่แนะนำด้านล่าง ผู้ที่ไม่มีเวลาเกิดจะไม่ถูกปรับ ค่าเริ่มต้น (ไม่ส่งก็ไม่ปรับ) ไม่เปลี่ยนแปลง
• เปลี่ยนแปลง 2026-10-11: หากส่งพิกัด ซาจูก็จะปรับเวลาสุริยะจริงด้วย (ก่อนหน้านี้ใช้เฉพาะกับดวงสมพงษ์ราศี) เป็นการแก้ไขให้ซาจูและราศีในการตอบกลับเดียวกันใช้เกณฑ์เวลาเดียวกัน การเรียกที่เคยส่งพิกัดจึงอาจได้คะแนนซาจู · เสาวันที่เปลี่ยนไป ส่วนการตอบกลับของการเรียกที่ไม่ได้ส่งฟิลด์ใหม่และพิกัดยังเหมือนเดิม
• เสาวันเป็นค่ารหัส: ค่าของ saju.personA.ilju · saju.personB.ilju (계미 ฯลฯ) จะส่งเป็นค่ารหัสก้าน-กิ่งภาษาเกาหลีไม่ว่า lang จะเป็นอะไร ชื่อที่จะแสดงบนหน้าจอให้แปลงด้วยอภิธานศัพท์ (glossary) ของ API ปฏิทินหมื่นปี หรือการเขียนด้วยฮันจา (癸未 สำหรับภาษาอังกฤษ · ภาษาไทยคือ 癸未 (Gye-mi))

การเรียกที่แนะนำ (ผลเดียวกับแอป INTA)

สำหรับผู้ที่ทราบเวลาเกิด ให้ส่งประเทศเกิดและ "exact" มาด้วยกัน การปรับเวลาสุริยะจริงจะเหมือนแอป INTA แม้ผู้ที่เวลาเกิดอยู่ใกล้เส้นแบ่งยามก็จะได้เสาวัน · คะแนนเหมือนในแอป

{
  "personABirthDate": "1990-09-04", "personABirthTime": "14:30", "personAGender": "male",
  "personACountry": "KR", "personABirthTimePrecision": "exact",
  "personBBirthDate": "1992-02-20", "personBBirthTime": "10:15", "personBGender": "female",
  "personBCountry": "KR", "personBBirthTimePrecision": "exact",
  "purpose": "yeonae_attraction", "details": true
}

ตัวอย่างการตอบกลับ

ด้านล่างคือผลลัพธ์จริงของเอนจิน (A ชาย 1990-09-04 14:30, B หญิง 1992-02-20 10:15 ความรัก ไม่มีพิกัด) ฟิลด์ที่รวมเสมอซึ่งเพิ่มเมื่อ 2026-10-10 (saju.relationRatings · saju.meetingKeywords · saju.authority · tti.conflictFrame) ถูกละไว้ในตัวอย่างนี้ — ดูตัวอย่างตัวเลือกด้านล่าง สองคนนี้แม้ส่งด้วยการเรียกที่แนะนำ (KR + exact) ก็ได้ค่าเดียวกัน

{
  "success": true,
  "data": {
    "personABirthDate": "1990-09-04", "personABirthTime": "14:30", "personAGender": "male",
    "personBBirthDate": "1992-02-20", "personBBirthTime": "10:15", "personBGender": "female",
    "tti": {
      "userTti": "말", "partnerTti": "원숭이",
      "relation": { "type": null, "detail": null, "relations": [] },
      "tier": "흉"
    },
    "saju": {
      "purpose": "yeonae_attraction",
      "hourKnown": { "a": true, "b": true },
      "personA": { "ilju": "임신" },
      "personB": { "ilju": "병인" },
      "score": { "total": 59, "grade": "맞춰 가면 좋아요",
                 "breakdown": { "ilju": 53, "authority": 65, "eightChar": 65 } },
      "axes": { "attraction": 25, "stability": 59, "growth": 58,
                "communication": 24, "passion": 74, "longevity": 65 },
      "pattern": { "name": "폭발형",
                   "description": "에너지가 크게 부딪히는 뜨거운 관계예요. 감정이 커질 때 잠시 쉬어 가는 규칙이 도움이 돼요." },
      "relation": { "summary": "천간충 + 인신충",
                    "stem": { "type": "천간충", "detail": "병임충" },
                    "branches": [ { "type": "지지충", "detail": "인신충" } ] },
      "elements": { "basis": "eight", "aLacks": [], "bProvidesToA": [], "bLacks": ["토"], "aProvidesToB": ["토"] },
      "tenGods": { "aView": "편재", "bView": "편관(칠살)" },
      "bestFor": ["단기 끌림"],
      "weakFor": ["결혼·동거"],
      "highlights": [ "상대의 시지에 나의 천을귀인 (사) 발현 — 상대가 나의 해결사" ],
      "iljuAxes": { "attraction": 45, "stability": 16, "growth": 88,
                    "communication": 60, "passion": 70, "longevity": 50 }
    },
    "categoryNarrative": {
      "category": "romantic", "purpose": "yeonae_attraction", "lang": "ko",
      "text": "상대 쪽의 즉각적인 열정과 나 쪽의 자유로운 흐름은 불과 물처럼 정면으로 맞부딪혀서, 처음 만났을 때의 팽팽한 긴장감이 곧 끌림이 되기 쉬워요. 짧고 뜨거운 설렘이 큰 관계라, 감정이 치솟는 날엔 하루쯤 식힐 틈을 두면 더 즐겁게 만날 수 있어요.",
      "styleVersion": "v2"
    },
    "costPoints": 20,
    "classic1995": {
      "symbol": "××", "grade": "대흉", "score": 50,
      "ttiRelation": { "type": null, "detail": null, "relations": [] },
      "conflictFrame": false
    },
    "relations": [
      { "positions": ["month", "month"], "kind": "chung", "tier": "heavyClash",
        "ruleIds": ["R-SAJU-REL-034", "R-SAJU-COMPAT-106", "R-SAJU-COMPAT-112"], "chars": ["申", "寅"] },
      { "positions": ["day", "day"], "kind": "chung", "tier": "heavyClash",
        "ruleIds": ["R-SAJU-REL-034", "R-SAJU-COMPAT-106", "R-SAJU-COMPAT-112"], "chars": ["申", "寅"] },
      { "positions": ["day", "day"], "kind": "stemChung", "tier": "clash",
        "ruleIds": ["R-SAJU-REL-008", "R-SAJU-COMPAT-110"], "chars": ["壬", "丙"] },
      { "positions": ["year", "year"], "kind": "napeumSaeng", "tier": "gather",
        "ruleIds": ["R-SAJU-BASE-037", "R-SAJU-COMPAT-111"], "chars": ["庚午", "壬申"] },
      { "positions": ["chart", "chart"], "kind": "banghap", "tier": "gather",
        "ruleIds": ["R-SAJU-REL-021", "R-SAJU-COMPAT-104"], "chars": ["巳", "午", "未"] }
    ],
    "p2Score": 57,
    "astroSynastry": {
      "self": {
        "sun": { "signEn": "Virgo", "element": "earth", "modality": "mutable" },
        "moon": { "signEn": "Pisces", "element": "water", "modality": "mutable", "uncertain": false },
        "ascendant": { "signEn": "Sagittarius", "element": "fire", "modality": "mutable", "uncertain": false, "countryBasis": true },
        "venus": { "signEn": "Leo", ... }, "mars": { "signEn": "Gemini", ... },
        "mercury": { ... }, "jupiter": { ... }, "saturn": { ... }
      },
      "partner": { "sun": { "signEn": "Pisces", ... }, "moon": { "signEn": "Virgo", ... }, ... },
      "layers": [
        { "key": "sun", "relation": "opposite", "selfSign": "Virgo", "partnerSign": "Pisces",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "key": "moon", "relation": "opposite", "selfSign": "Pisces", "partnerSign": "Virgo",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "key": "ascendant", "relation": "neutral", "selfSign": "Sagittarius", "partnerSign": "Taurus",
          "textKey": "compat.astro.relation.neutral",
          "text": "뚜렷한 결 없이 각자의 스타일을 존중하면 되는 조합이에요" }
      ],
      "purposeBodies": [
        { "body": "venus", "relation": "opposite", "selfSign": "Leo", "partnerSign": "Aquarius",
          "textKey": "compat.astro.relation.opposite",
          "text": "충 — 정반대라 방향은 다르지만 서로를 끌어당길 수 있어요" },
        { "body": "mars", "relation": "same_element", "selfSign": "Gemini", "partnerSign": "Aquarius",
          "textKey": "compat.astro.relation.same_element",
          "text": "같은 원소 — 서로의 방식을 바로 알아볼 만큼 편안할 수 있어요" }
      ],
      "caveats": ["compat.astro.caveat.ascendantCountryBasis"],
      "caveatTexts": ["상승궁은 출생 도시가 없어 국가 대표 좌표로 추정했어요"],
      "score": 64
    },
    "astroReadings": [
      { "key": "Su_Mo_ss", "lang": "ko",
        "text": "한쪽의 태양과 다른 쪽의 달이 같은 별자리에 놓이면, 한 사람이 향하는 방향을 다른 사람의 마음이 낯설지 않게 알아보는 깊은 공명이 생기기 쉬워요. 닮은 만큼 같은 그림자도 함께 커질 수 있으니 서로의 빈틈을 웃으며 짚어 주면 좋아요." },
      { "key": "Ve_Ma_op", "lang": "ko",
        "text": "한쪽의 금성과 다른 쪽의 화성이 정반대 별자리에 놓이면, 서로에게 없는 매력을 알아보며 끌리는 보완의 흐름이 생기기 쉬워요. 원하는 속도와 표현 방식이 반대로 기울 수 있으니 서로의 선을 말로 정해 두면 그 끌림이 편안하게 이어져요." }
    ],
    "headerBreakdown": {
      "sixAxis": 55, "authority": 65, "full8": 65, "classic": 57, "natal": 64,
      "average": 62, "purpose": "yeonae_attraction",
      "weights": { "sixAxis": 0.2, "authority": 0.3, "full8": 0.2, "classic": 0.1, "natal": 0.2 }
    },
    "engineVersion": "compat-2",
    "lang": "ko"
  }
}

• saju (ดวงสมพงษ์ซาจู) เป็นส่วนหลัก ในกรณีที่พบได้ยากซึ่งคำนวณเสาวันไม่ได้จะเป็น null — ในกรณีนั้นให้แสดงเฉพาะ tti
• saju.score.total: 0~100 ค่าเฉลี่ยของคะแนนตารางดวงสมพงษ์เสาวันและคะแนนการวิเคราะห์ 8 อักษร (แต่ละค่าอยู่ใน breakdown) grade คือระดับเป็นคำง่ายๆ — 아주 잘 맞아요 (เข้ากันดีมาก 85 ขึ้นไป) · 잘 맞아요 (เข้ากันดี 75 ขึ้นไป) · 무난해요 (พอไปได้ 65 ขึ้นไป) · 맞춰 가면 좋아요 (ปรับเข้าหากันจะดี 55 ขึ้นไป) · 서로 많이 달라요 (ต่างกันมาก) ค่านี้เหมือนเดิม — คะแนนที่รวมถึงตารางสัญลักษณ์ · ราศีคือ headerBreakdown.average
• saju.axes: 6 แกน แรงดึงดูด · ความมั่นคง · การเติบโต · การสื่อสาร · ความหลงใหล · ความยั่งยืน (0~100) เปลี่ยนไปตาม purpose saju.pattern: ชื่อและคำอธิบายประเภทความสัมพันธ์ (หากไม่มีเป็น null)
• saju.iljuAxes (ตั้งแต่ 2026-10-27): ค่าเดียวกับกราฟ 6 แกนบนหน้าจอผลลัพธ์ของแอป INTA — 6 แกนจากตารางดวงสมพงษ์ของคู่เสาวันสองคนตามเดิม (attraction · stability · growth · communication · passion · longevity 0~100 ไม่ขึ้นกับ purpose) ค่าเฉลี่ย 6 แกนคือ headerBreakdown.sixAxis คีย์เหมือน saju.axes แต่การคำนวณต่างกันจึงได้ตัวเลขต่างกัน หากตารางดวงสมพงษ์ไม่มีคู่นั้นจะเป็น null
• saju.elements: คำนวณจากการกระจายธาตุทั้งห้าของผังดวงทั้งหมดของสองคน (หากไม่ทราบเวลาใช้ 6 อักษร — basis: "six") bProvidesToA = ธาตุที่ A ไม่มีแต่ B มี
• saju.tenGods: สิบเทพของ B เมื่อมองจาก A (aView) และในทางกลับกัน (bView) highlights: ประโยคดาวพิเศษไขว้ที่พบใน 8 อักษร (สูงสุด 5 รายการ หากไม่มีเป็นอาร์เรย์ว่าง)
• relations (ตั้งแต่ 2026-10-16): รายการความสัมพันธ์ระหว่างผังดวงทั้งสอง ดูคู่กิ่งดินตำแหน่งเดียวกัน (ปี · เดือน · วัน · ยาม — เสายามเฉพาะเมื่อทั้งสองคนมีเวลาเกิด) การรวม · ปะทะของก้านฟ้าระหว่างก้านวันเกิดของทั้งสอง ธาตุนาบึมของเสาปี และรวมสาม · รวมทิศที่เกิดขึ้นได้เมื่อรวมผังดวงทั้งสอง แต่ละรายการมี positions ([ฝั่ง A, ฝั่ง B] — year · month · day · hour รวมสาม · รวมทิศคือ chart = ผังดวงทั้งหมด) kind (ตารางด้านล่าง) tier ruleIds (ID กฎ KB ที่เป็นหลักฐาน — ตรวจแหล่งที่มาต้นฉบับได้ใน KB API) chars (อักษรของความสัมพันธ์ เป็นฮันจา) ทุกคีย์ไม่ขึ้นกับภาษา แม้เปลี่ยน lang ก็เหมือนเดิม ข้อความบนหน้าจอให้สร้างเองจาก kind ไม่มีคำตัดสินว่าดีหรือไม่ดี หากตั้งผังดวงไม่ได้เป็น null หากไม่มีความสัมพันธ์เลยเป็นอาร์เรย์ว่าง
• tier: gather การรวมตัว (ฝั่งการรวม) · clash การขัดกัน · heavyClash การขัดกันรุนแรง (ความสัมพันธ์ที่ตำราจัดลำดับว่าหนักกว่า ตอนนี้คือการปะทะ) · listOnly แสดงในรายการเท่านั้น (ความสัมพันธ์ที่ไม่พบหลักฐานทิศทางในตำรา จึงไม่นำมาคิดคะแนน)
• p2Score (ตั้งแต่ 2026-10-16): 0~100 ค่าที่ตัด round(71.6 + 5 × Σ) ให้อยู่ใน 0~100 — Σ = ผลรวมของแต่ละความสัมพันธ์ gather +1 · clash −1 · heavyClash −2 · listOnly 0 1 หน่วย = 5 คะแนน และ 71.6 คือจุดกลางเมื่อไม่มีความสัมพันธ์เลย (ค่าเฉลี่ยจากสมาชิกจริงของคะแนนแกนตำราเดิม ณ 2026-10-16) ใช้มาตราเดียวกันไม่ว่าจะมีเสายามหรือไม่ ตำราบอกเพียงทิศทางและลำดับของความสัมพันธ์ ไม่ได้บอกขนาด — ตัวเลขนี้เป็นมาตราสมมติสำหรับแสดงบนหน้าจอ ไม่ใช่คะแนนจากตำรา (KB R-SAJU-COMPAT-113) หาก relations เป็น null จะเป็น null
• classic1995 (กำหนดยุติการรองรับ): ตอนนี้ยังมาเหมือนเดิมทุกอย่าง กำหนดการยุติ (ร่าง): ประกาศ 2026-11-16 → คงไว้ถึง 2026-12-31 → ตั้งแต่ 2027-01-01 เป็น null วันที่อาจเปลี่ยนตามประกาศการให้บริการ หากเชื่อมต่อใหม่ให้ใช้ relations · p2Score สัญลักษณ์ในตารางความเข้ากันลึกเสาวันชาย-หญิงของเอกสารอ้างอิง (1995) (● 대길 (ดีมาก) 100 · ◎ 중길 (ดีปานกลาง) 90 · ○ 길 (ดี) 80 · △ 무해무덕 (ไม่ดีไม่ร้าย) 70 · × 흉 (ร้าย) 60 · ×× 대흉 (ร้ายมาก) 50) ตารางนี้เป็นตารางทิศทางเสาวันชาย × เสาวันหญิง หากเป็นเพศเดียวกันหรือไม่ส่งเพศ จะอ่านทั้งสองทิศทาง (A เป็นชาย · B เป็นชาย) score คือค่าเฉลี่ยของสองคะแนน (เช่น 95) และ symbol · grade คือระดับที่ปัดค่าเฉลี่ยนั้นลงทีละ 10 คะแนน (เช่น 95 → ◎ 중길) หากสองทิศทางเหมือนกันจะใช้สัญลักษณ์นั้นตามเดิม conflictFrame: เป็น true เมื่อสัญลักษณ์ดีแต่ความสัมพันธ์ปีนักษัตรร้าย หรือกลับกัน หากหาเสาวันไม่ได้ทั้งหมดจะเป็น null
• astroSynastry: ดวงสมพงษ์ราศี layers = เปรียบเทียบ 3 ชั้น ดวงอาทิตย์ · ดวงจันทร์ · ลัคนา purposeBodies = ดาวที่ให้ความสำคัญตามวัตถุประสงค์ (ความรัก: ดาวศุกร์ · ดาวอังคาร แต่งงาน: +ดาวเสาร์ มิตรภาพ: ดาวพุธ · ดาวพฤหัสบดี …) relation = same_sign · opposite · same_element · element_support · same_modality · element_friction · neutral และ text คือคำอธิบายความหมาย (lang) score 0~100 caveats/caveatTexts: ระบุหากลัคนา · ราศีจันทร์เป็นค่าประมาณ หากไม่ทราบเวลา ชั้นลัคนาจะถูกตัดออก
• astroReadings: ย่อหน้าการอ่านที่เขียนไว้ล่วงหน้าสำหรับจุดสัมผัสที่โดดเด่นที่สุดในราศีของสองคน (ดวงอาทิตย์–ดวงจันทร์ ดาวศุกร์–ดาวอังคาร ฯลฯ) สูงสุด 2 รายการ หากไม่มีเป็นอาร์เรย์ว่าง lang ของแต่ละย่อหน้าคือภาษาจริงของประโยค (หากไม่มีประโยคในภาษาที่ขอเป็น ko)
• headerBreakdown: คะแนนรวม average (0~100) ที่รวมห้าคะแนน ได้แก่ ค่าเฉลี่ย 6 แกน · ผู้เชี่ยวชาญ (authority) · 8 อักษร (full8) · ส่วนของตำรา (classic — ตั้งแต่ 2026-10-16 คือ p2Score ก่อนหน้านั้นคือ classic1995.score) · ราศี (natal) ด้วยน้ำหนัก (weights) ตาม purpose คะแนนที่ขาดไปจะแบ่งน้ำหนักใหม่ให้ที่เหลือ เป็นค่าเดียวกับคะแนนหลัก (ตัวเลขใหญ่) บนหน้าจอดวงสมพงษ์ของแอป INTA (62 ในตัวอย่างข้างต้น) ตั้งแต่ 2026-10-16 น้ำหนักส่วนของตำรา (classic) สำหรับวัตถุประสงค์แต่งงาน (marriage_stability) ลดจาก 0.25 → 0.05 และส่วนที่ลดไป 0.20 ถูกแบ่งให้อีกสี่แกนตามสัดส่วนเดิม (sixAxis 0.15 → 0.19 · authority 0.25 → 0.3167 · full8 0.25 → 0.3167 · natal 0.10 → 0.1267) น้ำหนักของวัตถุประสงค์อื่นคงเดิม หากหาตารางดวงสมพงษ์เสาวันไม่ได้จะเป็น null
• ปีของวันเกิดต้องอยู่ระหว่าง 1900~2100 — หากเกินจะได้ 400 INVALID_BIRTH_YEAR (ไม่คิดค่าบริการ) หากพิมพ์ปีเป็นสองหลักในช่องป้อนวันที่จะกลายเป็นอย่าง 0090 ให้ป้องกันบนหน้าจอด้วย หากหาผลในตารางดวงสมพงษ์ไม่ได้จะได้ 400 COMPAT_UNAVAILABLE (ไม่คิดค่าบริการ)
• tti.tier: สตริงระดับของดวงสมพงษ์ปีนักษัตรจากเอกสารอ้างอิง (1995) (เช่น 대길 · 길 · 중길 · 보통 · 주의 · 흉 — จากดีมากถึงร้าย) tti.relation.type = ความสัมพันธ์ของกิ่งดินปีนักษัตรทั้งสอง — หนึ่งใน 충 (ปะทะ) · 원진 (ขุ่นเคือง) · 형 (ลงโทษ) · 해 (ทำร้าย) · 육합 (รวมหก) · 반합 (รวมครึ่ง) · 파 (ทำลาย) (หากหลายความสัมพันธ์ซ้อนกัน ใช้ตัวที่มาก่อนตามลำดับนี้) หากไม่มีเป็น null detail มีเฉพาะเมื่อเป็นรวมครึ่ง (เช่น 수국(水局)) tti.relation.relations = ความสัมพันธ์ที่ซ้อนกันทั้งหมด (ลำดับเดียวกัน เช่น ปีวัว · ปีแพะ ["충","형"] หากไม่มีเป็นอาร์เรย์ว่าง)
• tti มีเพียงปีนักษัตร · ความสัมพันธ์ · ระดับ ไม่ใส่ประโยคดวงสมพงษ์ปีนักษัตรจากเอกสารอ้างอิง (ตั้งแต่ 2026-10-11)
• categoryNarrative: 2~3 ประโยคที่บรรยายว่าสองคนเป็นอย่างไรในความสัมพันธ์นี้ (purpose) เป็นประโยคที่เขียนไว้ล่วงหน้าสำหรับคู่เสาวันของสองคน (1,830 คู่) และความสัมพันธ์ 6 ประเภท อินพุตเดียวกันจึงได้ประโยคเดิมเสมอ ในประโยค 나 = A, 상대 = B (ภาษาอังกฤษ You/Your partner ภาษาญี่ปุ่น あなた/相手 ภาษาไทย คุณ/คู่ของคุณ) มี 4 ภาษาตาม lang หากหาประโยคไม่ได้เป็น null (คิดค่าบริการเท่าเดิม)
• รวมเสมอ (ตั้งแต่ 2026-10-10): saju.relationRatings = { key, stars } ของความสัมพันธ์ 5 ประเภท (ตัวอย่าง key: 연애 (ความรัก) · 결혼·동거 (แต่งงาน · อยู่ด้วยกัน) · 친구 (เพื่อน) · 사업 파트너 (หุ้นส่วนธุรกิจ) · 장기 관계 (ความสัมพันธ์ระยะยาว) / ดาว 1~5) · saju.meetingKeywords = คีย์เวิร์ดการพบกัน 3 คำ · saju.authority = การตัดสินดวงสมพงษ์ตามผู้เชี่ยวชาญ (finalScore · grade · gradeTier · pattern · summary · levels (L1~L4) · factors · flags · climateBalance) · tti.conflictFrame = ค่าเดียวกับ classic1995.conflictFrame
• yearFlow.years[].tier: great · good · neutral · caution dayFlow.days[].tier: golden · good · neutral · dim · hard (dayFlow.golden/hard คือรายการวันที่ที่เกี่ยวข้อง)

ประเภทความสัมพันธ์ (relations[].kind)

kind เดียวกันมี tier เดียวกันเสมอ (ยกเว้นสองคู่ของการทำลาย) อาจมี kind ใหม่เกิดขึ้น จึงควรทำให้ข้ามค่าที่ไม่รู้จัก

ตัวอย่างตัวเลือก (details · flow · MBTI)

ตัดตอนผลลัพธ์จริงของเอนจิน คำขอ:

{
  "personABirthDate": "1990-05-15", "personABirthTime": "12:00", "personAGender": "male",
  "personBBirthDate": "1992-08-20", "personBBirthTime": "09:00", "personBGender": "female",
  "details": true, "flow": true, "date": "2026-10-10",
  "personAMbti": "ENFP", "personBMbti": "ISTJ"
}

{
  "success": true,
  "data": {
    "tti": { "userTti": "말", "partnerTti": "원숭이", ..., "tier": "흉", "conflictFrame": false },
    "saju": {
      "personA": { "ilju": "경진" }, "personB": { "ilju": "무진" },
      "score": { "total": 56, "grade": "맞춰 가면 좋아요", ... },
      ...,
      "relationRatings": [
        { "key": "연애", "stars": 3 }, { "key": "결혼·동거", "stars": 3 }, { "key": "친구", "stars": 4 },
        { "key": "사업 파트너", "stars": 3 }, { "key": "장기 관계", "stars": 3 }
      ],
      "meetingKeywords": ["괴강", "우직", "일반적 관계"],
      "authority": {
        "finalScore": 51, "grade": "주의", "gradeTier": "caution",
        "pattern": "자형 (자기 갈등 외부화)",
        "summary": "주의 · 자형 (자기 갈등 외부화) · 익숙한 결의 만남. 안락함 위에 자극을 어떻게 만들지가 핵심.",
        "levels": { "L1": { "raw": 0, "norm": 0 }, "L2": { "raw": 5, "norm": 14.3, "type": "동계절 (봄)" },
                    "L3": { "raw": 17, "norm": 56.7 }, "L4": { "raw": -17, "norm": -42.5 } },
        "factors": { "l1": [], "l2Tone": "...", "l3": [ ... ], "l4": ["자형(진진) — 자기 파괴 패턴", ...] },
        "flags": { "cheonHapJiHap": false, "dualChung": false },
        "climateBalance": "동계절 (봄)"
      },
      "conflict": {
        "pattern": "경은 무를 편인으로 인식. 일방향적 관계 성격.",
        "tip": "'괴강'과 '우직'은 서로 다른 결이에요. 같은 사건도 다르게 해석한다는 걸 인정하고, 서로의 관점을 한 번씩 빌려보세요."
      },
      "relationScores": { "stem": { "type": "편인", "category": "neutral", "score": 55 },
                          "branches": [ { "type": "자형", "score": -40 } ] },
      "full8": { "personA": { ... }, "personB": { ... }, "iljuEvaluation": { ... }, ... }
    },
    ...,
    "dictionary": { "a": { "id": "ilju_경진", "name_kr": "경진", "name_hanja": "庚辰", ... }, "b": { ... } },
    "yearFlow": {
      "baseYear": 2026,
      "years": [
        { "year": 2024, "score": 77, "tier": "great", "a": { ... }, "b": { ... },
          "summary": "두 분 모두 흐름이 좋아 같이 시작하기 좋은 해." },
        ...
      ]
    },
    "dayFlow": {
      "baseDate": "2026-10-10",
      "days": [
        { "date": "2026-10-03", "a": -89, "b": -40, "combined": -60, "tier": "hard", "isBaseDate": false },
        ...,
        { "date": "2026-10-10", "a": -9, "b": 27, "combined": 9, "tier": "neutral", "isBaseDate": true },
        ...
      ],
      "golden": [],
      "hard": [ { "date": "2026-10-03", "combined": -60 }, ... ],
      "summary": "3번 같이 가라앉는 날이 있어. 그날은 큰 결정·약속 미루자."
    },
    "mbti": { "id": "mbti_ENFP_ISTJ", "mbti_a": "ENFP", "mbti_b": "ISTJ",
              "socionics_relation": "Duality(이중관계)", "scores": { ..., "total": 64 }, ... }
  }
}

ข้อควรระวัง

• ข้อมูลพื้นฐาน: วันเกิดของทั้งสองคนเป็นข้อมูลจำเป็น เวลาและเพศไม่บังคับ แม้ไม่มีเพศหรือเพศเดียวกัน ตารางสัญลักษณ์ความเข้ากันลึกก็ยังออกมา (รวมสองทิศทาง) ส่วนลัคนาของดวงสมพงษ์ราศีต้องมีเวลาเกิดจึงจะออกมา
• โครงสร้างผลลัพธ์: ดวงสมพงษ์ราศีอิงจักรราศีแบบทรอปิคัล คำบรรยายตามความสัมพันธ์มาใน categoryNarrative และย่อหน้าราศีมาใน astroReadings ด้วยกัน หากต้องการคำอ่านเฉพาะบุคคลที่ยาวกว่านี้ ให้นำผลลัพธ์ไปใส่ในคำถามของ /reading
• เปลี่ยนแปลง 2026-10-16 (engineVersion compat-2): เพิ่ม relations · p2Score · engineVersion ใหม่ และ headerBreakdown.classic เปลี่ยนเป็น p2Score ทำให้ headerBreakdown.average อาจต่างจากเดิม (ค่าเดียวกับหน้าจอดวงสมพงษ์ของแอป INTA) ค่าของฟิลด์เดิมอื่นๆ คงเดิม
• ความเข้ากันได้: ฟิลด์ที่เพิ่มในเดือน 2026-10 (classic1995 · astroSynastry · astroReadings · headerBreakdown · lang และ saju.relationRatings · saju.meetingKeywords · saju.authority · tti.conflictFrame ของ 2026-10-10) จะแนบมาเสมอไม่ว่าจะส่ง lang หรือไม่ ค่าของฟิลด์เดิมคงเดิม แต่ตั้งแต่ 2026-10-11 ฟิลด์ที่ยกประโยคจากเอกสารอ้างอิง (1995) — คำอ่านหนึ่งบรรทัดของดวงสมพงษ์ปีนักษัตร และดวงความรัก · ดวงสุขภาพในพจนานุกรมเสาวัน — ถูกนำออกจากการตอบกลับแล้ว
• เพิ่มเมื่อ 2026-10-27: เพิ่ม saju.iljuAxes ใหม่ (เสมอ ท้ายสุดของบล็อก saju) ค่าและลำดับของฟิลด์เดิมคงเดิม และ engineVersion ก็ยังเป็น compat-2
• เปลี่ยนแปลง 2026-10-31: แก้คำช่วยในประโยคภาษาเกาหลีของดวงสมพงษ์ให้ตรงกับตัวสะกดท้าย (เช่น “임와” → “임과”, “병는” → “병은”) คีย์ · ลำดับ · ตัวเลข และประโยคภาษาอื่นคงเดิม
• ค่าใช้จ่าย: หัก ₩20 ต่อการเรียก (รวมฟิลด์เพิ่มเติม · ตัวเลือก details · flow · MBTI ไม่มีค่าบริการเพิ่ม)

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

ตัวอย่างคำขอดูได้ที่ตัวอย่างตัวเลือกข้างต้นและตัวอย่างการเรียกใช้

API ประเภทบุคลิกภาพ

ให้บริการแบบทดสอบบุคลิกภาพตาม MBTI รองรับเวอร์ชันไลต์ฟรี (24 ข้อ) และเวอร์ชันพรีเมียม (93 ข้อ)

GET /api/v1/partners/v1/personality-type/questions

ดึงข้อคำถามของแบบทดสอบบุคลิกภาพ ใช้ได้ฟรี

curl "https://api.hrum.ai/api/v1/partners/v1/personality-type/questions?tier=free" \
  -H "X-Partner-Api-Key: your-api-key"

พารามิเตอร์คำขอ

ตัวอย่างการตอบกลับ

{
  "success": true,
  "data": {
    "tier": "free",
    "count": 24,
    "questions": [
      {
        "id": "q_001",
        "text": "갑자기 생긴 모임에도 일단 가본다",
        "choices": [
          { "value": 1, "label": "전혀 그렇지 않다" },
          { "value": 2, "label": "그렇지 않다" },
          { "value": 3, "label": "보통이다" },
          { "value": 4, "label": "그렇다" },
          { "value": 5, "label": "매우 그렇다" }
        ]
      }
    ]
  }
}

POST /api/v1/partners/v1/personality-type

ส่งคำตอบของแบบทดสอบบุคลิกภาพเพื่อวิเคราะห์ประเภทบุคลิกภาพ

curl -X POST https://api.hrum.ai/api/v1/partners/v1/personality-type \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "free",
    "answers": [
      { "questionId": "q_001", "answer": 4 },
      { "questionId": "q_002", "answer": 2 }
    ]
  }'

พารามิเตอร์คำขอ

ตัวอย่างการตอบกลับ

{
  "success": true,
  "data": {
    "personalityType": "ENTJ",
    "typeLabel": "지휘관",
    "scores": {
      "extraversion": 72,
      "sensing": 45,
      "thinking": 68,
      "judging": 80
    },
    "tier": "premium",
    "costPoints": 10
  }
}

ราคา

• เวอร์ชันฟรี (free): 24 ข้อ ₩0 (ฟรี)
• พรีเมียม (premium): 93 ข้อ ₩10/ครั้ง
• questionId ที่ไม่มีอยู่หรือ answer นอก 1~5 จะได้ 400 และไม่คิดค่าบริการ
• ใน premium หากมีแกนที่ไม่มีคำตอบเลยจะได้ 400 personality_axis_unanswered และไม่คิดค่าบริการ axes ในการตอบกลับจะมีแกนที่ว่าง (E_I · S_N · T_F · J_P)

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป (401 · 400 การตรวจเนื้อหา · 402 · 429 · 503 ฯลฯ) แล้ว นี่คือรหัสที่ API นี้ส่งออกมา:

หากคำตอบอยู่นอก 1~5 จะได้ 400 ทั่วไป ทั้งหมดไม่คิดค่าบริการ

API ฐานข้อมูลการตีความ (KB)

API ที่เปิดเฉพาะบัญชีที่ยื่นขอ บัญชีที่ยังไม่เปิดจะได้ 404 kb_saju_explain_not_enabled ในทั้งสามเส้นทาง (ไม่คิดค่าบริการ) หากต้องการใช้ โปรดติดต่อฝ่ายสนับสนุน

อธิบายความสัมพันธ์ (การรวม · ปะทะ ฯลฯ) และโครงสร้าง (สิบเทพ · ก้านแฝง ฯลฯ) ที่เกิดขึ้นในผังดวงซาจูด้วยการ์ดกฎและประโยคคำอธิบาย ไม่ใช้ LLM อินพุตเดียวกันจึงได้ผลเดียวกันเสมอ

POST /api/v1/partners/v1/kb/saju/explain

พารามิเตอร์คำขอ

ตัวอย่างคำขอ

curl -X POST https://api.hrum.ai/api/v1/partners/v1/kb/saju/explain \
  -H "X-Partner-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "birth": {
      "year": 1990, "month": 5, "day": 17, "hour": 14, "minute": 30,
      "timezone": "Asia/Seoul", "gender": "female"
    },
    "sections": ["relations"]
  }'

ตัวอย่างการตอบกลับ (ตัดตอน)

{
  "success": true,
  "data": {
    "kbVersion": "2026.10.09-3",
    "kbHash": "sha256:24b9a2d9...",
    "channel": "stable",
    "chart": {
      "pillars": {
        "year":  { "stem": "庚", "branch": "午" },
        "month": { "stem": "辛", "branch": "巳" },
        "day":   { "stem": "壬", "branch": "午" },
        "hour":  { "stem": "丁", "branch": "未" }
      },
      "timeUnknown": false
    },
    "sections": [
      {
        "id": "relations",
        "title": "...",
        "steps": [
          {
            "fact": { "type": "stem_pair", "a": "壬", "b": "丁", "posA": "day", "posB": "hour", "relation": "hap" },
            "factText": "일간 壬과 시간 丁은 천간합(天干合) 관계다.",
            "componentId": "saju:stem_pair:丁壬:hap",
            "rules": [
              { "id": "R-SAJU-REL-004", "kind": "definition", "status": "verified", "sourceCount": 2,
                "statement": "丁과 壬은 천간합 관계이고, 이 짝의 합화 오행은 목(木)이다." }
            ],
            "interp": {
              "meaning": { "text": "丁(정)과 壬(임)은 천간합으로 묶이는 짝이고, ...", "reviewed": false },
              "why": { ... },
              "pitfall": { ... }
            }
          }
        ],
        "absent": [
          { "type": "stem_pair", "a": "庚", "b": "辛", "posA": "year", "posB": "month",
            "note": "庚과 辛은 천간합·천간충 어느 것도 아니다." }
        ]
      }
    ],
    "unregistered": [],
    "pendingReview": []
  }
}

• interp คือช่องคำอธิบาย (meaning ความหมาย · why เหตุผล · pitfall ข้อควรระวัง) แต่ละช่องเป็น {text, reviewed, reviewedBy?, notes?} และใน stable จะออกเฉพาะช่องที่ตรวจทานแล้ว
• unregistered: รายการที่เกิดขึ้นแต่ยังไม่มีคำอธิบาย pendingReview: รายการที่มีคำอธิบายแต่ยังไม่ตรวจทาน จึงซ่อนไว้ใน stable
• แหล่งที่มาจากตำราของการ์ดกฎดึงได้ด้วย GET /kb/rules/{id} ด้านล่าง

GET /api/v1/partners/v1/kb/rules/{id}

คืนการ์ดกฎหนึ่งใบพร้อมแหล่งที่มาจากตำรา ใช้ได้ฟรี

curl https://api.hrum.ai/api/v1/partners/v1/kb/rules/R-SAJU-REL-004 \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "id": "R-SAJU-REL-004",
    "kind": "definition",
    "statement": "丁과 壬은 천간합 관계이고, 이 짝의 합화 오행은 목(木)이다.",
    "status": "verified",
    "schools": [],
    "variantOf": null,
    "sources": [
      { "sourceId": "SRC-SMTH", "location": "“三命通會” 卷二 論十干化氣",
        "quote": "故丁與壬合　丁壬化木", "match": "EXACT", ... }
    ],
    "engineRef": "..."
  }
}

GET /api/v1/partners/v1/kb/release?domain=saju

คืนฉบับของฐานข้อมูลการตีความที่เผยแพร่อยู่ตอนนี้ ใช้ได้ฟรี หากละ domain จะเป็น saju (เช่น saju · ziwei · astro · dream · tarot)

curl "https://api.hrum.ai/api/v1/partners/v1/kb/release?domain=saju" \
  -H "X-Partner-Api-Key: your-api-key"

{
  "success": true,
  "data": {
    "version": "2026.10.09-3",
    "hash": "sha256:24b9a2d9...",
    "publishedAt": "2026-10-09T00:00:00.000Z",
    "channel": "stable",
    "counts": { "rules": 412, "interps": 1236 }
  }
}

ตัวเลขข้างต้นเป็นตัวอย่าง หากเก็บผลลัพธ์ไว้ ให้ดึงใหม่เมื่อ hash เปลี่ยน

รหัสข้อผิดพลาด

นอกจากข้อผิดพลาดทั่วไป: