YlanAI Analysis API Integration Guide

Access methods, available models, request specification, billing rules, and calling examples for the YlanAI Analysis API

Mar 25, 2026

This page explains the standard integration method for the YlanAI Analysis API.

The current interface follows an OpenAI-compatible protocol and works with clients that support chat/completions and completions.

The API output follows the same analysis standards as the in-product service. It is provided only for learning, research, communication, and entertainment reference, is not a guaranteed conclusion about future outcomes, and does not replace professional advice for medical, legal, compliance, or major financial matters.

1. Access Information

Base URL, request method, and standard endpoints

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

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

Authentication

All requests must include:

Authorization: Bearer sk-...

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

For third-party clients that cannot set Authorization, the service also accepts api-key: sk-... and x-api-key: sk-....

Multi-turn conversation

The interface supports multi-turn conversation. Callers can send prior messages in the messages array to preserve continuous context.

2. Scope And Models

Available scope

Scope	Description
Open capability	Structured analysis API only
General chat	Plain casual chat is not open
Supported scenarios	Single-person analysis and two-person relationship or collaboration analysis
Output standard	Follows the same structured analysis standard as the in-product service

Currently available models

The live GET /models response is the source of truth for currently available models. The platform may update the list over time.

Model	Description
`openai/gpt-5.4`	Best for high-quality structured analysis
`openai/gpt-5.3-chat`	Good for standard analysis and multi-turn dialogue
`deepseek/deepseek-v3.2`	Good for varied analysis and multi-turn dialogue

3. Request Specification

Response format

Scenario	Response format
`stream=true`	OpenAI-compatible SSE stream with `chat.completion.chunk` blocks and `data: [DONE]` as the end marker
`stream=false`	Standard `chat.completion` JSON response
`POST /completions`	OpenAI-compatible `text_completion` JSON or SSE stream
Successful non-stream headers	Returns `x-ylan-charged-credits` and `x-ylan-remaining-paid-credits` for the current deduction amount and remaining paid analysis allowance

Request parameters

Parameter	Type	Description
`model`	`string`	Model name returned by `GET /models`
`messages`	`array`	OpenAI-compatible messages array with at least one `user` message
`prompt`	`string`	Compatible with legacy `completions`; can be used for a single-turn text request when `messages` is omitted
`input`	`string`	Compatible with some third-party client input fields; can be used as the user question when `messages` is omitted
`stream`	`boolean`	Whether to use streaming responses, default `false`
`locale`	`string`	Response language, such as `zh`, `en`, or `ja`
`topic`	`string`	Analysis topic, such as `wealth_pattern` or `marriage_status`
`subject_mode`	`string`	Analysis mode, either `single` or `pair`
`method`	`string`	Analysis method resolved by the current analysis chain
`birth_profile`	`object`	Single-person analysis input for optional structured background information
`chart_input`	`object`	Existing structured input for scenarios where processing has already been done externally
`pair_state`	`object`	Two-person analysis input for relationship or collaboration scenarios
`metadata`	`object`	Extra metadata, such as `topic`, `locale`, `birthProfile`, or `pairState`

Example: single-person streaming request

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": "career_path",
    "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 current career adjustment priorities and action pace for the next six months based on my background."
      }
    ]
  }'

Example: two-person streaming request

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 communication priorities and long-term coexisting suggestions in this relationship based on both backgrounds."
      }
    ]
  }'

4. Billing And Error Handling

Billing rules and deduction timing

Scenario	Rule
Single-person analysis	100 analysis allowance per successful reply
Two-person relationship or collaboration analysis	200 analysis allowance per successful reply
`need_input`	No charge
Allowance scope	Only paid analysis allowance is consumed. Signup allowance and gifted allowance are excluded
`stream=true`	The deduction is confirmed after the first visible content chunk is returned
`stream=false`	The deduction is confirmed after the full successful response is returned
Timeout, failure, or empty response	No deduction is confirmed, or the amount is returned under the current rule

Common error codes

HTTP Status	Error code	Description
`400`	`invalid_messages`	The request is missing valid messages, or at least one `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 open list
`401`	`invalid_api_key`	The API key is invalid or missing
`402`	`insufficient_paid_credits`	The current account does not have enough paid analysis allowance
`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

Supplemental input response

When background information, topic information, or two-person information is insufficient, the API may return a need_input response asking for the missing conditions required for analysis. This type of response is not currently billed.