本命盘 API

基础 URL：https://api.natalchart.ai。每个请求都带有 API 密钥，每个响应都是 JSON，每个黄经在换算成星座之前都精确到度的小数点后四位。密钥免费：用 NatalChart.AI 账户登录，然后创建一个。

快速开始

curl https://api.natalchart.ai/v1/chart/short \
  -H "Authorization: Bearer $NATALCHART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birth":{"date":"1991-09-06","time":"18:30","latitude":50.4501,"longitude":30.5234}}'

响应如下，使用的是全站通用的演示出生数据（1991-09-06 18:30，基辅）。这里只显示其中五个天体：

{
  "sun": {
    "sign": "Virgo",
    "degreeInSign": 13.55,
    "house": 7
  },
  "moon": {
    "sign": "Leo",
    "degreeInSign": 19.02,
    "house": 7
  },
  "ascendant": {
    "sign": "Aquarius",
    "degreeInSign": 14.9898
  },
  "signs": {
    "Sun": "Virgo",
    "Moon": "Leo",
    "Mercury": "Leo",
    "Venus": "Leo",
    "Mars": "Libra"
  },
  "retrograde": [
    "Venus",
    "Saturn",
    "Uranus",
    "Neptune",
    "TrueNode",
    "Lilith",
    "Juno"
  ]
}

面向 AI 助手的 MCP 服务器

同样的计算也以 MCP 服务器的形式提供，地址为 https://www.natalchart.ai/mcp，适用于 Claude、ChatGPT、Cursor 和 VS Code。它使用同一个密钥，消耗同一份每日额度，每次工具调用计一次请求。各客户端的设置方法见面向 AI 助手的 MCP 服务器页面。

身份验证

以 Authorization: Bearer nc_live_... 的形式发送密钥（也可以用 X-API-Key 请求头）。完整的密钥只在创建时显示一次；我们只保存它的哈希值。一个账户最多可以有五个有效密钥，并可以立即撤销其中任何一个。请把密钥保存在服务器上：放进浏览器或应用代码里的密钥，任何人都能读取。

出生信息

计算星盘的端点接收一个对象：

{
  "birth": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timezone": "Europe/Kyiv"
  }
}

端点

完整星盘

POST /v1/chart/full 返回完整的计算结果，结构与已公开的演示文件相同，因此你在写任何代码之前，就可以拿一张固定的星盘核对响应。这里删减为两个天体、两个宫头和两个最紧密的相位：

{
  "input": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timeKnown": true
  },
  "time": {
    "timezone": "Europe/Kyiv",
    "offsetHours": 3,
    "julianDayUT": 2448506.1458333335
  },
  "planets": [
    {
      "name": "Sun",
      "longitude": 163.5457,
      "sign": "Virgo",
      "degreeInSign": 13.55,
      "speed": 0.9704,
      "retrograde": false,
      "house": 7
    },
    {
      "name": "Moon",
      "longitude": 139.0225,
      "sign": "Leo",
      "degreeInSign": 19.02,
      "speed": 14.5955,
      "retrograde": false,
      "house": 7
    }
  ],
  "angles": {
    "ascendant": {
      "longitude": 314.9898,
      "sign": "Aquarius"
    },
    "midheaven": {
      "longitude": 249.8956,
      "sign": "Sagittarius"
    }
  },
  "houses": [
    {
      "number": 1,
      "cusp": 314.9898,
      "sign": "Aquarius"
    },
    {
      "number": 2,
      "cusp": 13.7492,
      "sign": "Aries"
    }
  ],
  "aspects": [
    {
      "planet1": "Pallas",
      "planet2": "Juno",
      "aspect": "Square",
      "angle": 89.79,
      "orb": 0.21,
      "phase": "separating"
    },
    {
      "planet1": "Pluto",
      "planet2": "TrueNode",
      "aspect": "Sextile",
      "angle": 59.57,
      "orb": 0.43,
      "phase": "separating"
    }
  ],
  "elements": {
    "Fire": 7,
    "Earth": 6,
    "Air": 4,
    "Water": 2
  },
  "qualities": {
    "Cardinal": 6,
    "Fixed": 11,
    "Mutable": 2
  }
}

分段端点（planets、angles、houses、aspects、elements、fixed-stars）各返回同一对象中的一部分，供只需要这一部分的调用方使用。

每日运势

POST /v1/horoscope/daily 是每日运势中计算的那一半：UTC 正午的天空、月相和月亮星座、未来一周的天象事件；当你发送 birth 时，还包括对这张星盘的每个行运，附有相位、容许度、是入相位还是离相位、达到或已经达到精确的时刻，以及行运天体所在的本命宫位。月亮、太阳、水星、金星和火星的行运容许度为 2°，较慢的天体为 3°。有两个字段是固定规则而非天文计算，响应中也写明了这一点：tone（拱相和六分相为 supportive，刑相和冲相为 challenging，合相为 intensifying）和 focus，即按行星速度和紧密程度排名最高的三个接触。响应中没有成文的文字；这部分交给你。

演示星盘在 2026-09-18 的真实响应，列表删减为各两项：

{
  "date": "2026-09-18",
  "computedFor": "2026-09-18T12:00:00.000Z",
  "moon": {
    "phase": "First Quarter",
    "illumination": 46.5,
    "elongation": 86.04,
    "sign": "Sagittarius",
    "longitude": 261.6344,
    "degreeInSign": 21.63,
    "theme": "Decision + Action",
    "nextNewMoon": {
      "utc": "2026-10-10T15:50:05.436Z",
      "sign": "Libra",
      "degreeInSign": 17.36,
      "absoluteDegree": 197.36
    },
    "nextFullMoon": {
      "utc": "2026-09-26T16:49:02.781Z",
      "sign": "Aries",
      "degreeInSign": 3.62,
      "absoluteDegree": 3.62
    }
  },
  "positions": [
    {
      "name": "Sun",
      "longitude": 175.5994,
      "sign": "Virgo",
      "degreeInSign": 25.6,
      "speed": 0.9761,
      "retrograde": false
    },
    {
      "name": "Moon",
      "longitude": 261.6344,
      "sign": "Sagittarius",
      "degreeInSign": 21.63,
      "speed": 11.8869,
      "retrograde": false
    }
  ],
  "events": [
    {
      "kind": "ingress",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    },
    {
      "kind": "equinox",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    }
  ],
  "transits": [
    {
      "transit": "Vesta",
      "natal": "Mercury",
      "aspect": "Trine",
      "angle": 119.93,
      "orb": 0.07,
      "phase": "applying",
      "exactAt": "2026-09-18T21:43:39.997Z",
      "tone": "supportive",
      "transitHouse": 2,
      "houseTheme": "Money & Possessions"
    },
    {
      "transit": "Uranus",
      "natal": "Lilith",
      "aspect": "Trine",
      "angle": 119.86,
      "orb": 0.14,
      "phase": "separating",
      "exactAt": null,
      "tone": "supportive",
      "transitHouse": 3,
      "houseTheme": "Communication & Learning"
    }
  ],
  "focus": [
    {
      "transit": "Pluto",
      "natal": "Mars",
      "aspect": "Trine",
      "angle": 119.78,
      "orb": 0.22,
      "phase": "separating",
      "exactAt": "2026-09-03T17:58:04.996Z",
      "tone": "supportive",
      "transitHouse": 12,
      "houseTheme": "Spirituality & Subconscious"
    },
    {
      "transit": "Neptune",
      "natal": "Mars",
      "aspect": "Opposition",
      "angle": 179.74,
      "orb": 0.26,
      "phase": "separating",
      "exactAt": "2026-09-09T00:24:29.005Z",
      "tone": "challenging",
      "transitHouse": 1,
      "houseTheme": "Identity & Self"
    },
    {
      "transit": "Jupiter",
      "natal": "Moon",
      "aspect": "Conjunction",
      "angle": 1.77,
      "orb": 1.77,
      "phase": "applying",
      "exactAt": "2026-09-27T20:40:07.004Z",
      "tone": "intensifying",
      "transitHouse": 7,
      "houseTheme": "Partnerships & Marriage"
    }
  ]
}

API Pro 端点

六个端点，合起来就是应用所计算的全部内容。下面每个示例都是演示星盘的真实响应，有删减；请求中的 "..." 代表上文所示的出生信息对象。

一段时间内的行运

POST /v1/transits 接收 birth、from 和 to（最长 92 天），按日期返回该时间段内行运天体与本命盘形成的每个精确相位、每次进入星座和每次停滞，以及第一天正在生效的接触及其阶段和精确时刻。

{
  "window": {
    "from": "2026-09-18",
    "to": "2026-10-18"
  },
  "events": [
    {
      "kind": "aspect",
      "date": "2026-09-19",
      "body": "Mercury",
      "target": "Neptune",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-22",
      "body": "Jupiter",
      "target": "Pluto",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-23",
      "body": "Sun",
      "target": "Saturn",
      "aspect": "Trine",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-26",
      "body": "Sun",
      "target": "Mars",
      "aspect": "Conjunction",
      "exactness": 0,
      "significance": "low"
    }
  ]
}

合盘

POST /v1/synastry 接收 personA 和 personB，返回两盘之间的相位及容许度、每个人的行星落入对方的哪些宫位，以及六大生活领域各自的评分。这里的第二个人同样是虚构的（1989-03-14 07:45，纽约）。

{
  "aspects": [
    {
      "personA": "Neptune",
      "personB": "Lilith",
      "aspect": "Trine",
      "angle": 120.08,
      "orb": 0.08
    },
    {
      "personA": "Saturn",
      "personB": "Jupiter",
      "aspect": "Trine",
      "angle": 119.66,
      "orb": 0.34
    },
    {
      "personA": "Mercury",
      "personB": "Moon",
      "aspect": "Sextile",
      "angle": 60.38,
      "orb": 0.38
    }
  ],
  "sphereScores": {
    "identity": 89,
    "love": 81,
    "body": 86,
    "money": 76,
    "home": 83,
    "mind": 66
  }
}

太阳回归

POST /v1/solar-return 接收 birth、year 和可选的 location，返回太阳回到本命黄经的精确时刻，以及按这一时刻起的完整星盘。它需要出生时间：没有出生时间，本命太阳的位置会有半度的不确定，回归时刻也会因此偏移约十二小时。

{
  "year": 2027,
  "exactMomentUtc": "2027-09-06T08:29:55Z",
  "location": {
    "latitude": 50.4501,
    "longitude": 30.5234
  },
  "chart": "the full chart of that moment, in the shape of /v1/chart/full"
}

某项活动的最佳日子

POST /v1/timing 接收 birth、activity（general、business、romance、health、creative、travel、home 或 clarity）、from 和 to（最长 62 天），以及可选的 timezone，用来确定每一天从何时开始。每一天都根据精确的行运几何关系评出 0 到 100 分，并按对这项活动重要的行星加权，最好的五天排在最前。它描述的是天空，并不对某一天作出保证。

{
  "activity": "business",
  "best": [
    {
      "date": "2026-10-12",
      "score": 69.5,
      "rating": "good",
      "moonPhase": "New Moon",
      "moonSign": "Scorpio",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Moon (0.2°)",
        "Transit Mercury Sextile Sun (0.3°)",
        "Transit Mercury Sextile Neptune (0.2°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.8°)"
      ]
    },
    {
      "date": "2026-10-14",
      "score": 63.5,
      "rating": "good",
      "moonPhase": "Waxing Crescent",
      "moonSign": "Sagittarius",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Venus (1.1°)",
        "Transit Moon Sextile Saturn (0.7°)",
        "Transit Jupiter Conjunction Venus (0.1°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.7°)",
        "Transit Saturn Square Uranus (0.6°)"
      ]
    }
  ]
}

一个地点对照一张星盘

POST /v1/locations/score 接收 birth 和带坐标的 location。星盘会迁移到该地点，响应给出迁移后的四轴、落在四轴上的行星及其容许度、每个生活领域 0 到 10 分的评分（5 分为中性），以及这张星盘对该地点整体反应的强弱：有主要行星距某个轴点 2° 以内为强，4° 以内为中等，否则为弱。

{
  "relocated": {
    "ascendant": {
      "longitude": 277.7847,
      "sign": "Capricorn"
    },
    "midheaven": {
      "longitude": 210.708,
      "sign": "Scorpio"
    }
  },
  "angularPlanets": [
    {
      "planet": "Uranus",
      "angle": "ASC",
      "orb": 2.12,
      "weight": "major",
      "strength": "strong"
    },
    {
      "planet": "Neptune",
      "angle": "ASC",
      "orb": 6.31,
      "weight": "major",
      "strength": "weak"
    }
  ],
  "spheres": {
    "identity": {
      "score10": 1,
      "verdict": "challenging"
    },
    "love": {
      "score10": 6.1,
      "verdict": "slightly supportive"
    },
    "body": {
      "score10": 3.2,
      "verdict": "challenging"
    },
    "money": {
      "score10": 2.2,
      "verdict": "challenging"
    },
    "home": {
      "score10": 1.7,
      "verdict": "challenging"
    },
    "mind": {
      "score10": 4.9,
      "verdict": "neutral"
    }
  },
  "overall10": 2.2,
  "strength": "moderate"
}

最适合一张星盘的城市

POST /v1/locations/rank 接收 birth、可选的 focus（identity、love、body、money、home、mind 中的任意几项）、可选的 region，以及 3 到 12 之间的 limit，并为一份包含 61 个主要城市的目录排名。并非地球上的每座城市都参与比较；其他任何地点都可以用上面那个端点评分。

{
  "comparedCities": 61,
  "top": [
    {
      "city": "New York",
      "country": "United States",
      "overall10": 7.4,
      "focus10": 8.3,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.6°",
        "Moon MC 2.3°"
      ]
    },
    {
      "city": "Tbilisi",
      "country": "Georgia",
      "overall10": 7.4,
      "focus10": 8.2,
      "strength": "moderate",
      "contacts": [
        "Sun DSC 3.3°"
      ]
    },
    {
      "city": "Montreal",
      "country": "Canada",
      "overall10": 7.4,
      "focus10": 8.1,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.1°",
        "Moon MC 2.8°",
        "Mercury MC 3.8°"
      ]
    }
  ]
}

限额与价格

请求次数按账户统计，涵盖该账户的所有密钥，额度在 UTC 时间 00:00 恢复。每个响应都带有 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。因无效而被拒绝的请求不计数，因我们这边的原因而失败的计算会退还额度，GET /v1/usage 始终免费。API Pro 是独立于应用方案的订阅：它不包含应用的 Premium，应用的 Premium 也不包含它。两种额度同样相互独立：应用按周统计 AI 回答次数，这个 API 按 UTC 日统计计算次数，两者互不消耗。

错误

所有错误都采用同一种结构：{ "error": { "code", "message", "details"?, "docs" } }。

计算设置

这些设置是固定的，也就是应用本身的设置，完整说明见核对你的星盘页面，并在精度报告中与 NASA 的 JPL Horizons 进行了核对。使用 Swiss Ephemeris 数据文件，并开启速度标志。回归黄道，地心视位置。普拉西度制宫位。真交点。莉莉丝取月球密切远地点。幸运点按 ASC + 月亮 − 太阳计算，日间盘和夜间盘相同。只用五种主要相位：合相 8°、六分相 6°、刑相 8°、拱相 8°、冲相 8°。每个本命相位和行运相位都会标明是入相位还是离相位，根据两个天体的速度判断，包括逆行在内。

隐私

出生信息属于个人数据。API 读取它、完成计算、给出响应，然后就把它忘掉：不保存任何请求体，你发送的任何内容都只用于生成响应。我们为每个请求保留的是端点、状态码和延迟。详见隐私政策。

常见问题