时间主星API文档

时间主星（Timing）接口：返回黄道释放（zodiacal_release）和十年主星（ten_year_lords）两类时间技法的完整周期表。所有时间为 ISO 8601 带时区偏移，行星名为全大写。

基本信息

参数值
Base URLhttps://chart.12sign.top
接口URL/spc/timing
请求方式POST
Content-Typeapplication/json

请求参数

1. 基础参数（必需）

参数名类型必选说明
natal_data.datetimestring是出生日期时间，格式：YYYY-MM-DD HH:MM:SS
natal_data.latnumber是出生地纬度
natal_data.lonnumber是出生地经度
natal_data.tznumber/string是出生地时区，如 8 表示UTC+8（返回时间的时区偏移与此一致）

2. 可选参数

参数名类型默认值说明
techniquesarray["zodiacal_release", "ten_year_lords"]要计算的技法列表，可选值："zodiacal_release"（黄道释放）、"ten_year_lords"（十年主星）
ai_promptbooleanfalsetrue 时返回 ai_prompt 字段：按固定模板填充观测时刻（需配合 zodiacal_release.focus_time）的真实盘面数据——当前大限主星与 ZR L1/L2 链、飞星落宫、先天/后天得分、解缚/角宫巅峰、吉凶矩阵——供 LLM 生成解读
zodiacal_release.from_fortunebooleanfalse是否以福点为释放起点（默认以日盘太阳/夜盘月亮为起点）
zodiacal_release.start_signintegernull起释星座序号：0=白羊 … 11=双鱼（与返回 sign_index 同口径）；传值时忽略 from_fortune；null = 默认起点（日盘太阳/夜盘月亮所在星座，from_fortune=true 时为福点所在星座）
zodiacal_release.lotstringnull起释专项点：fortune 福点 / spirit 精神点 / eros 爱欲点 / necessity 困顿点 / courage 勇气点 / victory 胜利点 / nemesis 仇敌点 / basis 根基点 / children 子女点（从该 Lot 落座起释，Lot 落点按 Paulus 日/夜公式由 ASC 与行星推算）；null = 默认（日盘太阳/夜盘月亮所在星座，from_fortune=true 时为福点）；指定 lot 时优先于 start_sign 与 from_fortune
zodiacal_release.levelsinteger2输出层级：2 = 含二级子周期（默认）；3/4 = 下钻模式，需配合 focus_time，返回焦点链上的三级/四级周期
zodiacal_release.focus_timestringnull下钻时刻，YYYY-MM-DD HH:MM:SS（本命地时）。levels≥3 时必填；返回包含该时刻的 L2 段的三级周期（levels=4 再深入其四级周期）
zodiacal_release.include_testimoniesbooleanfalsetrue 时每段附带本命行星证词（testimonies / ruler_witnessed 字段）
zodiacal_release.yearsnumber/nullnull只输出到指定年数；null = 输出完整一轮（12 章）
zodiacal_release.engine_tablebooleantruetrue（默认）用引擎周期表（天秤 8 年，与 Valens 原典及主流工具一致）；false 用天秤 25 年的变体表
zodiacal_release.sub_methodstring/nullnull子周期算法：null（默认，原典填充法）或 "proportional"（比例法）
ten_year_lords.yearsnumber/nullnull只输出到指定年数；null = 输出全部 7 个大限
ten_year_lords.start_planetstring/nullnull起始行星（SUN/MOON/MERCURY/VENUS/MARS/JUPITER/SATURN）；null = 日盘取太阳、夜盘取月亮
ten_year_lords.rotationstring/nullnull大限轮转序："zodiacal"（默认，按星盘黄经序，Valens 原文及 astro-seek 等主流工具口径）或 "chaldean"（固定迦勒底轮）
ten_year_lords.levelsinteger2输出层级：2 = 大限+子限（默认）；3 = 附微限（每个子限按小年比例再分 7 段，顺序从该子限主星起转）

请求示例

{
    "natal_data": {
        "datetime": "1990-06-15 14:30:00",
        "lat": 39.9,
        "lon": 116.4,
        "tz": 8
    },
    "techniques": ["zodiacal_release", "ten_year_lords"],
    "zodiacal_release": {"from_fortune": false, "levels": 2},
    "ten_year_lords": {"rotation": null}
}

返回参数

参数名类型说明
successboolean请求是否成功
ai_promptstringai_prompt=true 时返回：已用真实盘面数据填充完成的解读提示词全文
birth_timestring出生时刻，ISO 8601 带时区偏移（与 natal_data.tz 一致）
is_dayboolean昼夜盘判定结果（日盘 true）
zodiacal_release.start_sign_index / start_signinteger / string释放起点星座编号（0=白羊）与名称
zodiacal_release.from_fortuneboolean是否福点释放
zodiacal_release.periodsarray主周期章节列表，每项见下表
ten_year_lords.orderarray大限行星序列（全大写）
ten_year_lords.rotationstring使用的轮转序
ten_year_lords.periodsarray大限列表，每项见下表
errorsobject计算失败的技法及原因（全部成功时无此字段）

zodiacal_release.periods 每项的字段

字段类型说明
sign_index / signinteger / string星座编号（0=白羊）/ 中文名
yearsnumber本章年数
start_age / end_agenumber起止年龄（年）
start_time / end_timestring起止时间，ISO 8601 带时区偏移
order_from_startinteger本章是起点的第几星座（1-12）
has_peakboolean本章是否含峰值期
peak_periodobject/null峰值期（起点的第 10 个星座段），字段含 sign_index/sign/start_age/end_age/start_time/end_time
sub_periodsarray子周期列表，每项含 sign_index/sign/start_age/end_age/start_time/end_time/house/ruler/is_peak
段内 houseinteger段星座在本命整宫盘中的宫位（上升星座=第1宫，顺数；Hellenistic 整宫制口径）
sub_periods[].l3_periodsarray三级周期，levels≥3 时仅 focus_time 命中的 L2 段携带，字段同 sub_periods
sub_periods[].l3_periods[].l4_periodsarray四级周期，levels=4 时仅 focus 命中的 L3 段携带，字段同 sub_periods
段内 testimoniesarrayinclude_testimonies=true 时返回：本命行星对段星座的整宫相位证词，每项含 planet/aspect（conjunction/sextile/square/trine/opposition）/quality（superior=先行侧/inferior=后行侧/空）/sect（昼夜派标注，全七政随盘判断：日盘太阳/夜盘月亮=in-sect light（本盘派系光体），相对侧=out-of-sect light；日盘木星/夜盘金星=in-sect benefic；日盘土星/夜盘火星=in-sect malefic（节制），相对侧为 out-of-sect；水星按晨昏相位归派=in-sect/out-of-sect mercury）
段内 ruler_witnessedbooleaninclude_testimonies=true 时返回：段守护星是否见证（与段星座构成相位）
段内 loosing_bondboolean该段是否为"松绑"段（子周期循环满一圈回到起点星座时，按 Valens 规则跳至对宫继续，该段即松绑段）
period_rolestring段角色："peak"（峰值段）/"build-up"（积累段）。L1 层峰值=释放点起数第 10 位的章（major 主峰，全盘唯一）；L2-L4 层峰值=上级起点起数第 10 位的子段（minor 次峰）
peak_scalestring仅峰值段有值："major"（L1 主峰）/"minor"（L2-L4 次峰）；积累段为 null

ten_year_lords.periods 每项的字段

字段类型说明
lordstring大限主星（全大写）
months / start_month / end_monthinteger大限月数及起止月
start_time / end_timestring起止时间，ISO 8601 带时区偏移
sub_periodsarray子限列表，每项含 lord/months/start_month/end_month/start_time/end_time
sub_periods[].sub_sub_periodsarray微限列表，levels=3 时返回，每项含 lord/months/start_month/end_month/start_time/end_time

返回示例（节选）

{
    "success": true,
    "birth_time": "1990-06-15T14:30:00+08:00",
    "is_day": true,
    "zodiacal_release": {
        "start_sign_index": 2, "start_sign": "双子", "from_fortune": false,
        "periods": [
            {
                "sign_index": 2, "sign": "双子", "years": 20,
                "start_age": 0.0, "end_age": 20.0,
                "start_time": "1990-06-15T14:30:00+08:00",
                "end_time": "2010-03-02T14:30:00+08:00",
                "order_from_start": 1, "has_peak": true,
                "peak_period": {"sign_index": 11, "sign": "双鱼", "start_age": 16.0833, "end_age": 17.0833,
                                 "start_time": "2006-04-22T14:30:00+08:00", "end_time": "..."},
                "sub_periods": [
                    {"sign_index": 2, "sign": "双子", "start_age": 0.0, "end_age": 1.6667,
                     "start_time": "1990-06-15T14:30:00+08:00", "end_time": "..."},
                    ...
                ]
            },
            ...
        ]
    },
    "ten_year_lords": {
        "order": ["SUN", "JUPITER", "SATURN", "MOON", "MARS", "VENUS", "MERCURY"],
        "rotation": "zodiacal",
        "periods": [
            {
                "lord": "SUN", "months": 129, "start_month": 0, "end_month": 129,
                "start_time": "1990-06-15T14:30:00+08:00",
                "end_time": "2001-01-18T14:30:00+08:00",
                "sub_periods": [
                    {"lord": "SUN", "months": 19, "start_month": 0, "end_month": 19,
                     "start_time": "1990-06-15T14:30:00+08:00", "end_time": "1992-01-06T14:30:00+08:00"},
                    ...
                ]
            },
            ...
        ]
    }
}

Python 调用示例

import requests

response = requests.post('https://chart.12sign.top/spc/timing', json={
    "natal_data": {"datetime": "1990-06-15 14:30:00", "lat": 39.9, "lon": 116.4, "tz": 8}
})
d = response.json()
for seg in d['zodiacal_release']['periods']:
    print(f"黄道释放 L1: {seg['sign']} {seg['start_time']} ~ {seg['end_time']}")
for mj in d['ten_year_lords']['periods']:
    print(f"十年主星: {mj['lord']} {mj['start_time']} ~ {mj['end_time']}")

在线测试

请求地址：
https://chart.12sign.top/spc/timing
请求参数（JSON）：
返回结果：
点击"发送请求"后在此显示结果