Fortune API Integration Guide

Access method, supported models, request specification, billing rules, and examples for the YlanAI fortune API

Mar 25, 2026

This page describes the standard integration method for the YlanAI fortune API.

The current interface follows the OpenAI-compatible protocol and is intended for clients that use chat/completions and completions.

1. Access Information

Base URL, request method, and standard endpoints

Item	Description
Preferred base URL	`https://ylan.ai/api/openai`
Compatibility base URL	`https://ylan.ai/api/openai/v1`
Default method	`POST`
Model list endpoint	`GET /models`
Model detail endpoint	`GET /models/{id}`
Chat endpoint	`POST /chat/completions`
Legacy completion endpoint	`POST /completions`

For third-party clients that append /v1 automatically, use https://ylan.ai/api/openai as the configured base URL.

Authentication

Every request must include:

Authorization: Bearer sk-...

The API key belongs to the current user account, and usage is deducted from that account's paid credit pool.

For third-party clients that cannot set Authorization, compatibility headers api-key: sk-... and x-api-key: sk-... are also accepted.

Multi-turn conversation

Multi-turn conversations are supported. Clients can preserve context by carrying prior messages in the messages array.

2. Scope and Models

Service scope

Scope	Description
Exposed capability	Only fortune-analysis capability is exposed
General chat	General-purpose chat is not available through this API
Supported scenarios	Both single-subject analysis and pair analysis are supported
Output standard	Analytical capability and output standards are aligned with the in-product fortune experience

Supported models

The source of truth is the real-time result of GET /models. The available set may be updated as platform capability evolves.

Model	Description
`openai/gpt-5.4`	High-quality fortune-analysis scenarios
`openai/gpt-5.3-chat`	General fortune interpretation and multi-turn dialogue
`deepseek/deepseek-v3.2`	Diverse fortune-analysis and multi-turn dialogue

3. Request Specification

Response format

Scenario	Response
`stream=true`	Returns an OpenAI-compatible SSE stream with `chat.completion.chunk` payloads and a terminating `data: [DONE]`
`stream=false`	Returns a standard `chat.completion` JSON response
`POST /completions`	Returns an OpenAI-compatible `text_completion` JSON response or SSE stream
Successful non-stream headers	Includes `x-ylan-charged-credits` and `x-ylan-remaining-paid-credits`

Request parameter reference

Parameter	Type	Description
`model`	`string`	Model name returned by `GET /models`
`messages`	`array`	OpenAI-compatible message array; at least one `user` message is required
`prompt`	`string`	Legacy `completions` input; can be used when `messages` is omitted
`input`	`string`	Compatibility input field used by some third-party clients when `messages` is omitted
`stream`	`boolean`	Whether to use streaming output; default is `false`
`locale`	`string`	Output language, such as `en`, `zh`, or `ja`
`topic`	`string`	Fortune topic, such as `wealth_pattern` or `marriage_status`
`subject_mode`	`string`	Analysis mode, `single` or `pair`
`method`	`string`	Analysis method resolved by the current fortune pipeline
`birth_profile`	`object`	Single-subject input for explicit birth details
`chart_input`	`object`	Structured chart input for externally prepared chart scenarios
`pair_state`	`object`	Pair-analysis input
`metadata`	`object`	Extended metadata that can supplement `topic`, `locale`, `birthProfile`, `pairState`, and related fields

Single-subject streaming request example

curl -N https://ylan.ai/api/openai/chat/completions \
  -H 'Authorization: Bearer sk-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-5.4",
    "stream": true,
    "locale": "en",
    "topic": "wealth_pattern",
    "subject_mode": "single",
    "birth_profile": {
      "calendar": "solar",
      "birthDate": "1992-08-15",
      "birthTime": "09:30",
      "gender": "male",
      "location": "Shenzhen"
    },
    "messages": [
      {
        "role": "user",
        "content": "Please analyze my financial outlook for this year."
      }
    ]
  }'

Pair-analysis streaming request example

curl -N https://ylan.ai/api/openai/chat/completions \
  -H 'Authorization: Bearer sk-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "deepseek/deepseek-v3.2",
    "stream": true,
    "locale": "en",
    "topic": "marriage_status",
    "subject_mode": "pair",
    "pair_state": {
      "subjects": [
        {
          "birthProfile": {
            "calendar": "solar",
            "birthDate": "1992-08-15",
            "birthTime": "09:30",
            "gender": "male",
            "location": "Shenzhen"
          }
        },
        {
          "birthProfile": {
            "calendar": "solar",
            "birthDate": "1995-03-08",
            "birthTime": "22:15",
            "gender": "female",
            "location": "Guangzhou"
          }
        }
      ]
    },
    "messages": [
      {
        "role": "user",
        "content": "Please analyze the long-term direction of this relationship and the key points for compatibility."
      }
    ]
  }'

Scenario	Rule
Single-subject analysis	100 credits per successful reply
Pair analysis	200 credits per successful reply
`need_input`	Not billed
Credit scope	Only paid credits can be consumed; signup bonus and gifted credits are excluded
`stream=true`	Credits are confirmed when the first visible content chunk is returned
`stream=false`	Credits are confirmed after the full successful response is returned
Timeout, failure, empty response	The charge is not confirmed or is refunded under the current rules

HTTP Status	Error Code	Description
`400`	`invalid_messages`	The request has no valid messages or no `user` message
`400`	`invalid_prompt`	The request is missing `messages`, `prompt`, and `input` at the same time
`400`	`invalid_model`	The requested model is not in the current allowlist
`401`	`invalid_api_key`	The API key is missing or invalid
`402`	`insufficient_paid_credits`	The account does not have enough paid credits
`500`	`request_timeout`	The request timed out
`500`	`request_failed`	The request failed
`500`	`internal_error`	Internal server error
`502`	`empty_response`	The model returned no visible content

When birth details, topic details, or pair-analysis inputs are incomplete, the API may return a need_input style response. This response is only used to collect prerequisites for the analysis and is not billed.

Fortune API Integration Guide

1. Access Information

2. Scope and Models

3. Request Specification

4. Billing and Error Handling