명리 API 연동 가이드

YlanAI 명리 분석 API의 접속 방법, 지원 모델, 요청 규격, 과금 규칙 및 호출 예시

3월 25, 2026

이 문서는 YlanAI 명리 분석 API의 표준 연동 방식을 설명합니다.

현재 인터페이스는 OpenAI 호환 프로토콜을 따르며, chat/completions 및 completions 를 지원하는 클라이언트에서 사용할 수 있습니다.

1. 접속 정보

주소, 요청 방식 및 표준 엔드포인트

항목	설명
권장 기본 주소	`https://ylan.ai/api/openai`
호환 기본 주소	`https://ylan.ai/api/openai/v1`
기본 요청 방식	`POST`
모델 목록	`GET /models`
모델 상세	`GET /models/{id}`
대화 엔드포인트	`POST /chat/completions`
레거시 `completions` 엔드포인트	`POST /completions`

클라이언트가 /v1 을 자동으로 붙이는 경우에는 https://ylan.ai/api/openai 를 우선 사용하세요.

인증 방식

모든 요청에는 아래 헤더가 필요합니다.

Authorization: Bearer sk-...

API Key 는 현재 사용자 계정에 귀속되며, 사용량은 해당 계정의 유료 크레딧 풀에서 차감됩니다.

Authorization 헤더를 설정할 수 없는 일부 서드파티 클라이언트를 위해 api-key: sk-... 및 x-api-key: sk-... 도 호환 헤더로 지원합니다.

멀티턴 대화

멀티턴 대화를 지원합니다. 호출 측은 messages 배열에 이전 대화 내용을 포함해 문맥을 유지할 수 있습니다.

2. 공개 범위와 모델

서비스 범위

범위	설명
공개 기능	명리 분석 API 만 공개
일반 채팅	공개하지 않음
지원 시나리오	단일 대상 분석과 2인 합판 분석 지원
출력 기준	사이트 내부 경험과 동일한 기준 적용

사용 가능 모델

사용 가능 모델은 GET /models 의 실시간 결과를 기준으로 합니다. 플랫폼 기능 확장에 따라 변경될 수 있습니다.

모델	설명
`openai/gpt-5.4`	고품질 명리 분석에 적합한 모델
`openai/gpt-5.3-chat`	일반 명리 해석과 멀티턴 대화에 적합한 모델
`deepseek/deepseek-v3.2`	다양한 명리 분석과 멀티턴 대화에 적합한 모델

3. 요청 규격

응답 형식

조건	응답 형식
`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 호환 메시지 배열. 최소 1개의 `user` 메시지가 필요
`prompt`	`string`	레거시 `completions` 입력. `messages` 가 없을 때 단일 텍스트 입력으로 사용 가능
`input`	`string`	일부 서드파티 클라이언트 호환 입력 필드. `messages` 가 없을 때 사용 가능
`stream`	`boolean`	스트리밍 응답 사용 여부. 기본값은 `false`
`locale`	`string`	출력 언어. 예: `ko`, `zh`, `en`
`topic`	`string`	명리 주제. 예: `wealth_pattern`, `marriage_status`
`subject_mode`	`string`	분석 모드. `single` 또는 `pair`
`method`	`string`	현재 명리 체인에서 해석하는 분석 방식
`birth_profile`	`object`	단일 대상 분석용 출생 정보
`chart_input`	`object`	외부에서 준비한 구조화 명식 입력
`pair_state`	`object`	2인 합판 분석용 입력
`metadata`	`object`	`topic`, `locale`, `birthProfile`, `pairState` 등을 보완하는 확장 메타데이터

단일 대상 스트리밍 예시

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": "ko",
    "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": "올해 제 재물 흐름을 분석해 주세요."
      }
    ]
  }'

2인 합판 스트리밍 예시

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": "ko",
    "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": "두 사람의 관계 방향성과 궁합의 핵심 포인트를 분석해 주세요."
      }
    ]
  }'

4. 과금 및 오류 처리

과금 규칙 및 과금 확정 시점

조건	규칙
단일 대상 분석	성공한 응답마다 100 크레딧 차감
2인 합판 분석	성공한 응답마다 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 응답

출생 정보, 주제 정보 또는 2인 분석 정보가 부족한 경우 API 는 need_input 형태의 보완 응답을 반환할 수 있습니다. 이 응답은 분석 전제 조건을 보완하기 위한 것이며 과금되지 않습니다.