紫微星斗大师

根据性别、历法、出生日期、时间和地点生成紫微主题文化解读，适合传统文化阅读产品。

支持公历与农历资料，并提供农历闰月标记，便于表达不同历法下的出生信息。

结果包含基本信息，便于读者先核对查询对象和出生资料，再阅读对应的文化内容。

提供命盘摘要作为报告的阅读入口，便于展示主题提要并连接各项详细解读。

包含十二宫位的文化解读，可在报告中按宫位分组展示并保留各自的解释内容。

提供主星与辅星相关说明，适合将传统星曜术语与具体解读组合成阅读章节。

提供四化分析内容，便于在紫微主题报告中单独呈现这一传统文化解释维度。

包含大限与流年主题的文化内容，可按不同时间维度组织章节，方便读者对照阅读。

提供综合建议与分项说明，便于在完整报告之外制作摘要页和章节导航。

支持同步返回、异步任务及流式获取，可用于完整报告查询或逐步展示的文化阅读页面。

相关解读仅供娱乐、传统文化研究与参考，不代表经科学验证的预测，不应作为医疗、法律、投资、婚姻或职业等重要现实决策的唯一依据。
Demo 是固定公开输入的静态样例，用于展示响应格式，不代表实时生成。
支持 JSON、表单与既有鉴权位置；重复业务参数或冲突凭据返回参数错误。
任务受理时预留调用额度，成功完成后确认扣次，失败或未完成过期时退回；轮询不扣次。
流式使用 type=content/text 片段、type=done/full_text 完整 JSON 文本、event=end/data=[DONE]。错误或不完整输出没有成功终态。

当前接口契约

接口详情：https://www.gugudata.com/api/details/ziwei-fortune

请求参数

参数	类型	必填	默认值	说明
appkey	string	是	无	付费后获取的 APPKEY
gender	string	是	无	性别，如：男、女。
calendarType	string	是	无	历法类型，如：公历、农历。
birthDate	string	是	无	出生日期，格式：YYYY-MM-DD。
birthTime	string	是	无	出生时间，格式：HH:MM。
birthPlace	string	是	无	非空白出生地点，作为传统文化解读的补充资料。
isLeapMonth	boolean	否	false	农历出生时是否为闰月，公历场景可保持 false。
streaming	boolean	否	false	默认 false；true 使用 SSE：type=content/text 片段、type=done/full_text 完整 JSON 文本、event=end/data=[DONE]。错误或不完整流不发送成功终态。task 模式必须为 false。
responseMode	string	否	sync	默认 sync；task 返回受理结果，通过 pollingUrl 查询。调用包在受理时预留，成功确认扣次，失败或未完成过期时退回；轮询不扣次。

正常响应字段

字段	类型	说明
DataStatus.RequestParameter	string	本次完整真实业务输入，以可读 JSON 展示，不包含鉴权凭据。
DataStatus.StatusCode	integer	接口返回状态码
DataStatus.StatusDescription	string	接口返回状态说明
DataStatus.ResponseDateTime	string	接口数据返回时间
DataStatus.DataTotalCount	integer	此条件下的总数据量，一般用于分页计算
Data.基本信息	object	命盘推演所使用的基础出生信息
Data.命盘摘要	string	对整体命格与人生节奏的综合概述
Data.十二宫位	object	命宫、财帛宫、事业宫等十二宫位的解读
Data.主星与辅星	object	主星格局与辅星亮点分析
Data.四化分析	object	化禄、化权、化科、化忌的推演结果
Data.大限	array	分阶段的大限主题与趋势解读
Data.流年趋势	object	近一年、近三年的趋势变化与提醒
Data.综合建议	object	事业、财运、感情、健康等方向的综合建议
Data.operationId	string	仅 responseMode=task 时返回，任务唯一标识。
Data.status	string	仅 responseMode=task 或轮询接口返回，状态枚举：PENDING、RUNNING、SUCCEEDED、FAILED、EXPIRED。
Data.pollingUrl	string	仅 responseMode=task 或轮询接口返回，任务状态查询地址。
Data.expiresAt	string	仅 responseMode=task 或轮询接口返回，任务结果过期时间。
Data.result	object	仅任务状态为 SUCCEEDED 时返回，业务结果结构与同步模式一致。
Data.error	object	仅任务状态为 FAILED 时返回，失败原因信息。
Data.免责声明	string	传统文化解读的适用范围与使用说明。

业务状态说明

业务状态码	业务状态码解释	备注
100	请求成功	请同时检查 HTTP 状态、业务码与异步任务状态；任务受理不代表完成。
501	参数错误	请同时检查 HTTP 状态、业务码与异步任务状态；任务受理不代表完成。
502	请求频率受限	请同时检查 HTTP 状态、业务码与异步任务状态；任务受理不代表完成。
503	订单已到期	请同时检查 HTTP 状态、业务码与异步任务状态；任务受理不代表完成。
504	APPKEY 错误	请同时检查 HTTP 状态、业务码与异步任务状态；任务受理不代表完成。
505	调用额度耗尽	请同时检查 HTTP 状态、业务码与异步任务状态；任务受理不代表完成。
-9	处理失败	请同时检查 HTTP 状态、业务码与异步任务状态；任务受理不代表完成。
901	文化解读暂不可用	请同时检查 HTTP 状态、业务码与异步任务状态；任务受理不代表完成。

请求参数

Query 参数

Header 参数

Body 参数application/json必填

示例

{
  "gender": "女",
  "calendarType": "公历",
  "birthDate": "1990-12-01",
  "birthTime": "07:00",
  "birthPlace": "江苏苏州",
  "isLeapMonth": false,
  "responseMode": "sync",
  "streaming": false
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢200成功

application/json

接口正常响应。请求成功，业务状态请结合响应体中的自定义业务码判断。

Bodyapplication/json

示例

{
    "DataStatus": {
        "ResponseDateTime": "string",
        "DataTotalCount": 0,
        "RequestParameter": "string",
        "StatusDescription": "string",
        "StatusCode": 0
    },
    "Data": {
        "主星与辅星": {
            "property1": "string",
            "property2": "string"
        },
        "expiresAt": "string",
        "error": {
            "property1": "string",
            "property2": "string"
        },
        "流年趋势": {
            "property1": "string",
            "property2": "string"
        },
        "四化分析": {
            "property1": "string",
            "property2": "string"
        },
        "pollingUrl": "string",
        "命盘摘要": "string",
        "operationId": "string",
        "大限": [
            {}
        ],
        "result": {
            "property1": "string",
            "property2": "string"
        },
        "综合建议": {
            "property1": "string",
            "property2": "string"
        },
        "status": "string",
        "十二宫位": {
            "property1": "string",
            "property2": "string"
        },
        "基本信息": {
            "property1": "string",
            "property2": "string"
        }
    }
}

🟠400参数无效，业务码 501。

🟠401鉴权失败。缺少 appkey 或 appkey 无效。

🟠403无权限访问。订单到期、权限不足或接口额度不可用。

🟠404资源不存在。请求路径不存在。

🟠405请求方法不允许。当前路径不支持该 HTTP 方法。

🟠415请求内容类型不支持。上传或请求体的内容类型不符合接口要求。

🟠429请求频率受限。默认情况下，每个接口提供 5 QPS 并发能力，可满足大多数业务场景。超出当前并发能力时，网关可能返回 429 请求频率受限；如需更高吞吐，可按需购买额外 QPS 扩展包，高频调用场景支持白名单接入与独立流控策略。

🔴500服务内部错误。服务端处理异常，请稍后重试。

🔴502服务暂时不可用。数据服务暂时不可用，请稍后重试。

🔴503文化解读暂不可用，业务码 901；失败不返回占位成功结果。

当前接口契约#

请求参数#

正常响应字段#

业务状态说明#

请求参数

请求示例代码

返回响应

当前接口契约

请求参数

正常响应字段

业务状态说明