Skip to main content

apiworks-astro-py-sdk

Python SDK for ApiWorks 星盘 API(www.apiworks.com)。支持星盘、八字、紫微、七政四余、奇门遁甲、大六壬、星宿、运势、AI 报告等能力(SDK v1.2.0)。

功能概览

  • 星盘 (Chart):本命盘、天象盘、行运盘、比较盘、组合盘、三限/次限/法达/日弧等
  • 星座 (Sign):我的星座、星座列表、星座配对
  • 运势 (Scope):日/周/月/年运势
  • 星象事件 (Event):行运星象事件
  • 紫微斗数 (Ziwei):本命盘、排盘、含解读的排盘
  • 七政四余 (Zhengyu):本命盘、行运排盘、比较盘、神煞目录
  • 星宿 (Naks):27 星宿关系
  • 八字 (Bazi):命盘、流盘、合盘、总结
  • 三式 (Sanshi):奇门遁甲、大六壬 / 金口诀
  • 报告 (Report):桃花、周运、年运、合盘、财运等 AI 报告
  • 多语言:请求体 / 查询参数 lang,支持 zh-Hans(默认)、zh-Hant、en(部分接口)

安装

pip install apiworks-astro-py-sdk

或从源码安装(在项目目录下):

pip install -e .

依赖

  • Python >= 3.9
  • httpx >= 0.27
  • pydantic >= 2.0

凭证(App ID / App Key)

每个 AstroCloudClient / AsyncAstroCloudClient 实例绑定一对 app_id 与 app_key,该实例发出的全部请求都会带上这组凭证。

ApiWorks 网站上,同一开放域下不同能力可能对应不同的 App ID / App Key(具体以网站开通为准,分组可能调整)。请按你实际开通的凭证使用:

  • 同一对凭证能调用哪些接口 → 以网站控制台为准
  • 需要用多组凭证时 → 为每组各建一个 Client,不要混用
from apiworks_astro_sdk import AstroCloudClient, QimenQry, SinglePointQry

# 凭证 A:例如开通了星盘相关接口
chart_client = AstroCloudClient(app_id="chart-app-id", app_key="chart-app-key")
chart_client.chart_natal(SinglePointQry(
    birth_dt="1990-08-14 12:00:00", tz=8, longitude=116.4, latitude=39.9,
))

# 凭证 B:例如开通了奇门 / 六壬相关接口
sanshi_client = AstroCloudClient(app_id="sanshi-app-id", app_key="sanshi-app-key")
sanshi_client.qimen(QimenQry(qry_dt="1999-10-17 21:00:00", tz=8))

若返回鉴权失败,请到网站 Token 管理页核对:该组 App ID / App Key 是否有权调用目标接口,且二者是否为一组配套凭证。

快速开始

同步客户端

from apiworks_astro_sdk import AstroCloudClient, SinglePointQry, TimeAndLocation

# 传入在网站上对该接口有权限的那一对凭证
client = AstroCloudClient(
    app_id="your-app-id",
    app_key="your-app-key",
)
# base_url 默认为 https://cloud.apiworks.com/open/astro,如需可传入 base_url 覆盖

# 本命盘
qry = SinglePointQry(
    birth_dt="1990-08-14 12:00:00",
    tz=8,
    longitude=116.4074,
    latitude=39.9042,
)
resp = client.chart_natal(qry)  # ApiResp[AstroDataVo],强类型
if resp.code == 0 and resp.data:
    print(resp.data.house, resp.data.planet)

异步客户端

import asyncio
from apiworks_astro_sdk import AsyncAstroCloudClient, ScopeQryReq, TimeAndLocation, ScopeRespVo

async def main():
    client = AsyncAstroCloudClient(
        app_id="your-app-id",
        app_key="your-app-key",
    )
    qry = ScopeQryReq(
        birth_point=TimeAndLocation(
            birth_dt="1990-01-01 12:00:00", tz=8, longitude=116.4, latitude=39.9
        ),
        transit_point=TimeAndLocation(
            birth_dt="2025-02-26 12:00:00", tz=8, longitude=116.4, latitude=39.9
        ),
    )
    resp = await client.scope_day("user-123", qry)  # ApiResp[ScopeRespVo]
    if resp.code == 0 and resp.data:
        scope: ScopeRespVo = resp.data
        print(scope.scope_total, scope.scope_info)

asyncio.run(main())

更多示例

八字命盘:

from apiworks_astro_sdk import AstroCloudClient, BaziNatalQry, BaziNatalVO

client = AstroCloudClient(app_id="...", app_key="...")
qry = BaziNatalQry(birth_dt="1990-08-14 12:00:00", tz=8, gender="male")
resp = client.bazi_natal(qry)  # ApiResp[BaziNatalVO]
if resp.code == 0 and resp.data:
    natal: BaziNatalVO = resp.data
    print(natal.pillars, natal.flow_decadal)

紫微本命盘:

from apiworks_astro_sdk import AstroCloudClient, ZiweiNatalQry, ZiweiNatalVo

qry = ZiweiNatalQry(birth_dt="1999-10-17 21:00:00", tz=8, gender="female")
resp = client.ziwei_natal(qry)  # ApiResp[ZiweiNatalVo]
if resp.code == 0 and resp.data:
    ziwei = resp.data
    print(ziwei.natal.palaces, ziwei.patterns)

星宿关系:

from apiworks_astro_sdk import AstroCloudClient, NaksQry, NaksBirthInfo, NaksVo

qry = NaksQry(
    birth_info=NaksBirthInfo(birth_dt="1990-01-15 00:00:00", tz=8),
    others_birth_info=[
        NaksBirthInfo(birth_dt="1992-03-20 00:00:00", tz=8),
    ],
)
resp = client.naks_relations(qry)  # ApiResp[NaksVo]
if resp.code == 0 and resp.data:
    naks: NaksVo = resp.data
    print(naks.natal_naks_info, naks.others_natal_relation)

七政四余:

from apiworks_astro_sdk import (
    AstroCloudClient,
    QizhengNatalQry,
    QizhengQry,
    QizhengComparisonQry,
    QizhengPersonQry,
)

client = AstroCloudClient(app_id="...", app_key="...")

natal = client.zhengyu_natal(QizhengNatalQry(
    birth_dt="1973-09-05 05:48:31", tz=8, gender="male",
))
chart = client.zhengyu_chart(QizhengQry(
    birth_dt="1973-09-05 05:48:31", tz=8, gender="male",
    target_dt="2026-08-28 12:00:00",
))
cmp_ = client.zhengyu_comparison(QizhengComparisonQry(
    user_list=[
        QizhengPersonQry(birth_dt="1973-09-05 05:48:31", tz=8, gender="male"),
        QizhengPersonQry(birth_dt="2000-06-15 12:00:00", tz=8, gender="female"),
    ],
))

奇门遁甲 / 大六壬:

from apiworks_astro_sdk import AstroCloudClient, QimenQry, LiurenQry

client = AstroCloudClient(app_id="...", app_key="...")

# 时家拆补转盘
qm = client.qimen(QimenQry(
    qry_dt="1999-10-17 21:00:00",
    tz=8,
    type="shijia",
    pai_method="zhuanpan",
    ju_method="chaibu",
    lang="zh-Hans",
))
if qm.code == 0 and qm.data:
    print(qm.data.ju_display, qm.data.jiu_gong.keys())

# 大六壬
lr = client.liuren(LiurenQry(
    qry_dt="1999-10-17 21:00:00",
    tz=8,
    type="daliuren",
    gui_method="tian",
))
if lr.code == 0 and lr.data:
    print(lr.data.ge_ju, lr.data.si_ke, lr.data.san_chuan)

双点星盘(行运/比较盘):

from apiworks_astro_sdk import AstroCloudClient, DoublePointQry, TimeAndLocation, AstroDataVo

qry = DoublePointQry(
    user_list=[
        TimeAndLocation(birth_dt="1990-08-14 12:00:00", tz=8, longitude=116.4, latitude=39.9),
        TimeAndLocation(birth_dt="2025-02-26 12:00:00", tz=8, longitude=116.4, latitude=39.9),
    ]
)
resp = client.chart_transit(qry)   # ApiResp[AstroDataVo] 行运盘
resp = client.chart_comparison(qry) # ApiResp[AstroDataVo] 比较盘
if resp.code == 0 and resp.data:
    print(resp.data.planet, resp.data.house)

报告(桃花/合盘/周运等):

from apiworks_astro_sdk import AstroCloudClient, RomanticCreateQry, TimeAndLocation, AstroReportVo

qry = RomanticCreateQry(
    user_birth_point=TimeAndLocation(
        birth_dt="1990-01-01 13:14:15", tz=8, longitude=116.4, latitude=39.9
    ),
    user_current_point=TimeAndLocation(
        birth_dt="2025-11-26 13:14:15", tz=8, longitude=116.4, latitude=39.9
    ),
    user_id="user-123",
)
resp = client.report_romantic(qry)  # ApiResp[AstroReportVo]
if resp.code == 0 and resp.data and resp.data.serial_no:
    serial_no = resp.data.serial_no  # 可用 report_get / report_get_html 拉取报告

API 响应格式

所有接口均返回强类型 ApiResp[T],可直接使用 resp.code、resp.msg、resp.data、resp.exe_time,其中 data 为与接口对应的 Vo 类型(如 BaziNatalVO、NaksVo、AstroDataVo 等):

resp = client.bazi_natal(qry)  # ApiResp[BaziNatalVO]
assert resp.code == 0
data: BaziNatalVO = resp.data  # 强类型,IDE 可补全

验证 SDK 是否可用

用真实接口调用一次本命盘,确认网络与凭证正常:

# 在项目根目录,先安装本包与依赖(含 pytest 可加 --extras dev)
poetry install

# 设置你的 app_id / app_key 后执行(不要提交到仓库)
export APIWORKS_APP_ID="你的app_id"
export APIWORKS_APP_KEY="你的app_key"
poetry run python scripts/verify_sdk.py

也可不用 Poetry:

pip install -e ".[dev]"
APIWORKS_APP_ID=xxx APIWORKS_APP_KEY=xxx python scripts/verify_sdk.py

成功会打印 验证通过,SDK 可用。;若 code != 0 或报错,请检查凭证与网络。

项目结构

apiworks-astro-py-sdk/
├── pyproject.toml
├── README.md
├── src/
│   └── apiworks_astro_sdk/
│       ├── __init__.py
│       ├── client.py       # AstroCloudClient, AsyncAstroCloudClient
│       └── models/
│           ├── __init__.py
│           ├── common.py            # ApiResp, TimeAndLocation
│           ├── requests.py           # 各类请求 DTO(含 lang / 政余 / 奇门 / 六壬)
│           ├── responses.py          # 响应 VO
│           ├── qizheng_responses.py  # 七政四余响应 VO
│           └── sanshi_responses.py   # 奇门 / 大六壬响应 VO
└── tests/

License

MIT

Metadata

Release files for apiworks-astro-py-sdk 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for apiworks-astro-py-sdk 1.2.0
File Size Uploaded Provenance Actions
apiworks_astro_py_sdk-1.2.0.tar.gz 20.1 kB Without provenance Details for apiworks_astro_py_sdk-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for apiworks-astro-py-sdk 1.2.0
File Interpreter ABI Platform Actions
apiworks_astro_py_sdk-1.2.0-py3-none-any.whl Python 3 none any Details for apiworks_astro_py_sdk-1.2.0-py3-none-any.whl

Total release size: 43.8 kB

Release files / apiworks_astro_py_sdk-1.2.0.tar.gz

Download URL apiworks_astro_py_sdk-1.2.0.tar.gz
Size 20.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a5320f7951c47752f6b0311d6692eaef5fb08172897c2502f92f2c30b7b53d50
BLAKE2b-256 checksum
How to use checksums
3973bec6f437f9bb2a0f32e69490123ac0b5eb9c1d133153a39738f040f4caf0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.22

Release files / apiworks_astro_py_sdk-1.2.0-py3-none-any.whl

Download URL apiworks_astro_py_sdk-1.2.0-py3-none-any.whl
Size 23.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
96e7a8af39caeb9e756336e6b546b2b961561b7292809be432e71f0be64802a3
BLAKE2b-256 checksum
How to use checksums
7db5b3cf49c56dd7cc51d41184ebbcaa7d0b851b880b78731890bb0ab248e904
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.22

Security for apiworks-astro-py-sdk 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page