YlanAI 분석 API 연동 가이드

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

Mar 25, 2026

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

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

API 출력은 제품 내부 서비스와 동일한 분석 기준을 따릅니다. 학습, 연구, 교류, 오락적 참고를 위한 용도로만 제공되며, 미래 결과를 보장하는 결론이 아니고 의료, 법률, 컴플라이언스, 중대한 재무 사안에 대한 전문 판단을 대체하지도 않습니다.

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 형태의 보완 응답을 반환할 수 있습니다. 이 응답은 분석 전제 조건을 보완하기 위한 것이며 과금되지 않습니다.