开放命理 API 接入指南

易览AI开放命理 API 的接入方式、可用模型、请求规范、计费规则与调用示例

2026/03/25

本页用于说明易览AI开放命理 API 的标准接入方式。

当前接口遵循 OpenAI 兼容协议，适用于支持 chat/completions 与 completions 的客户端。

一、接入信息

接口地址、请求方式与标准端点

项目	说明
接口首选地址	`https://ylan.ai/api/openai`
兼容基地址	`https://ylan.ai/api/openai/v1`
默认请求方式	`POST`
模型列表接口	`GET /models`
模型详情接口	`GET /models/{id}`
对话接口	`POST /chat/completions`
旧版补全兼容接口	`POST /completions`

对于会自动追加 /v1 的第三方客户端，建议优先使用 https://ylan.ai/api/openai 作为接口地址。

鉴权方式

所有请求均需在请求头中传入：

Authorization: Bearer sk-...

API Key 归属于当前用户账户，调用消耗将从该账户的付费积分池中扣减。

对于无法设置 Authorization 的第三方客户端，当前也兼容 api-key: sk-... 与 x-api-key: sk-... 两种请求头写法。

多轮对话方式

接口支持多轮对话。调用方可通过 messages 数组携带历史消息，以实现连续上下文对话。

二、可用范围与模型

可用范围

范围	说明
开放能力	仅开放命理分析 API
通用聊天	不开放普通通用聊天
支持场景	支持单人命理分析与双人合盘分析
结果口径	与站内命理分析能力保持一致

当前可用模型

可用模型以 GET /models 的实时返回结果为准，平台将根据能力规划持续更新。

模型名称	说明
`openai/gpt-5.4`	高质量命理分析场景
`openai/gpt-5.3-chat`	通用命理解读与连续对话
`deepseek/deepseek-v3.2`	多样化命理分析与连续对话

三、请求规范

返回格式

场景	返回格式
`stream=true`	返回 OpenAI 兼容的 SSE 数据流，数据块类型为 `chat.completion.chunk`，结束标记为 `data: [DONE]`
`stream=false`	返回标准 `chat.completion` JSON 响应
`POST /completions`	返回 OpenAI 兼容的 `text_completion` JSON 或 SSE 数据流
非流式成功响应头	返回 `x-ylan-charged-credits` 与 `x-ylan-remaining-paid-credits`

请求参数说明

参数	类型	说明
`model`	`string`	模型名称，需来自 `GET /models` 返回结果
`messages`	`array`	OpenAI 兼容消息数组，至少包含一条 `user` 消息
`prompt`	`string`	兼容旧版 `completions` 请求；未传 `messages` 时可直接传入单轮文本
`input`	`string`	兼容部分第三方客户端的输入字段；未传 `messages` 时可作为用户问题使用
`stream`	`boolean`	是否使用流式返回，默认 `false`
`locale`	`string`	返回语言，如 `zh`、`en`、`ja`
`topic`	`string`	命理专题，如 `wealth_pattern`、`marriage_status`
`subject_mode`	`string`	分析模式，取值为 `single` 或 `pair`
`method`	`string`	分析方式，按当前命理链路解析
`birth_profile`	`object`	单人分析输入，适用于出生信息明确的请求
`chart_input`	`object`	命盘结构化输入，适用于外部已完成排盘的场景
`pair_state`	`object`	双人合盘输入，适用于合盘分析
`metadata`	`object`	扩展元数据，可补充 `topic`、`locale`、`birthProfile`、`pairState` 等字段

单人命理流式请求示例

curl -N https://ylan.ai/api/openai/chat/completions \
  -H 'Authorization: Bearer sk-你的APIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-5.4",
    "stream": true,
    "locale": "zh",
    "topic": "wealth_pattern",
    "subject_mode": "single",
    "birth_profile": {
      "calendar": "solar",
      "birthDate": "1992-08-15",
      "birthTime": "09:30",
      "gender": "male",
      "location": "深圳"
    },
    "messages": [
      {
        "role": "user",
        "content": "请分析我今年的财运走势。"
      }
    ]
  }'

双人命理流式请求示例

curl -N https://ylan.ai/api/openai/chat/completions \
  -H 'Authorization: Bearer sk-你的APIKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "deepseek/deepseek-v3.2",
    "stream": true,
    "locale": "zh",
    "topic": "marriage_status",
    "subject_mode": "pair",
    "pair_state": {
      "subjects": [
        {
          "birthProfile": {
            "calendar": "solar",
            "birthDate": "1992-08-15",
            "birthTime": "09:30",
            "gender": "male",
            "location": "深圳"
          }
        },
        {
          "birthProfile": {
            "calendar": "solar",
            "birthDate": "1995-03-08",
            "birthTime": "22:15",
            "gender": "female",
            "location": "广州"
          }
        }
      ]
    },
    "messages": [
      {
        "role": "user",
        "content": "请结合双方命盘，分析这段关系的长期发展与相处重点。"
      }
    ]
  }'

四、计费与错误处理

计费规则与扣费时点

场景	规则
单人命理分析	每次成功回复扣减 100 积分
双人合盘分析	每次成功回复扣减 200 积分
`need_input`	不扣费
积分范围	仅消耗付费积分，不消耗注册送积分或赠送积分
`stream=true`	首个有效可见内容返回后确认扣费
`stream=false`	完整成功响应返回后确认扣费
超时、失败、空响应	不确认扣费或按当前规则返还

常见错误码

HTTP 状态	错误码	说明
`400`	`invalid_messages`	请求缺少有效消息，或至少缺少一条 `user` 消息
`400`	`invalid_prompt`	请求同时缺少 `messages`、`prompt` 与 `input`
`400`	`invalid_model`	请求模型不在当前开放名单内
`401`	`invalid_api_key`	API Key 无效或缺失
`402`	`insufficient_paid_credits`	当前账户付费积分不足
`500`	`request_timeout`	请求超时
`500`	`request_failed`	请求失败
`500`	`internal_error`	服务端内部错误
`502`	`empty_response`	模型未返回有效可见内容

补充信息响应

当出生信息、专题信息或双人信息不足时，接口可能返回 need_input 类型的补充提示。该类响应仅用于补全分析所需条件，当前不计费。