API 문서

XHuoAPI는 OpenAI Chat Completions 형식을 지원하며, Claude 모델은 Anthropic Messages 형식도 지원합니다. 하나의 키로 70개 이상의 모델을 쓸 수 있습니다.

인터랙티브 API 레퍼런스(온라인으로 바로 호출) →

Base URL

https://api.xhuoapi.ai

빠른 시작

콘솔에서 계정 등록
콘솔에서 API 키 발급
Base URL을 https://api.xhuoapi.ai로 변경
API 호출 시작

지원 엔드포인트

아래 각 항목은 실제 API 키로 검증했습니다. 표에 없는 엔드포인트는 경로가 응답하더라도 동작을 보장하지 않습니다.

마지막 검증: 2026-10-05 · Base URL https://api.xhuoapi.ai

엔드포인트	형식	설명
POST `/v1/chat/completions`	OpenAI	모든 채팅 모델. stream, tools, response_format은 deepseek-v3.2에서 검증했으며, 다른 모델의 지원 여부는 공급자에 따라 다릅니다.
POST `/v1/messages`	Anthropic	Claude 모델(claude-sonnet-4-6로 검증). 인증은 x-api-key와 Authorization: Bearer 모두 사용할 수 있습니다.
GET `/v1/models`	OpenAI	키로 사용할 수 있는 모든 모델을 나열합니다.
POST `/v1/embeddings`	OpenAI	text-embedding-3-small은 1536차원 벡터를 반환합니다. 카탈로그에는 text-embedding-3-large와 text-embedding-ada-002도 있습니다(별도 검증 안 함).

OpenAI SDK의 base_url에는 https://api.xhuoapi.ai/v1을 넣습니다. Anthropic SDK에는 https://api.xhuoapi.ai를 넣으면 SDK가 /v1/messages를 직접 붙입니다.

인증

모든 요청은 HTTP 헤더에 API 키를 포함해야 합니다:

Authorization: Bearer YOUR_API_KEY

⚠️ 보안 안내: API 키를 클라이언트 코드에 노출하지 마세요. 자체 백엔드를 통해 요청을 프록시하는 것을 권장합니다.

채팅 완성

채팅 완성 요청을 생성합니다. 모든 주요 모델을 지원합니다.

POST /v1/chat/completions

요청 파라미터

파라미터	유형	필수	설명
`model`	string	✅	모델 이름 (예: `gpt-4o`)
`messages`	array	✅	대화 메시지 목록
`temperature`	number	❌	샘플링 온도 (0-2), 기본값 1
`max_tokens`	integer	❌	생성할 최대 토큰 수
`stream`	boolean	❌	스트리밍 출력 여부, 기본값 false

요청 예시

curl https://api.xhuoapi.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "안녕하세요, 자기소개를 해주세요"
      }
    ],
    "temperature": 0.7
  }'

응답 예시

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "안녕하세요! 저는 AI 어시스턴트입니다..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 20,
    "total_tokens": 32
  }
}

모델 목록

사용 가능한 모든 모델 목록을 가져옵니다.

GET /v1/models

요청 예시

curl https://api.xhuoapi.ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

검증된 자주 쓰는 모델

아래 모델은 최근 검증에서 정상적으로 응답했습니다(날짜는 '지원 엔드포인트' 참고). 전체 목록과 그룹별 가격은 가격 페이지에 있습니다.

deepseek-v3.2

DeepSeek

qwen3.8-max

Alibaba · Qwen

glm-5.3

Zhipu · GLM

kimi-k3

Moonshot · Kimi

claude-sonnet-4-6

Anthropic

gpt-4.1-mini

OpenAI

gemini-2.5-flash

Google

스트리밍

stream: true를 설정하면 생성되는 내용을 실시간으로 받을 수 있습니다.

요청 예시

curl https://api.xhuoapi.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "농담 하나 해줘"}],
    "stream": true
  }'

응답 형식

스트리밍 응답은 Server-Sent Events (SSE) 형식을 사용하며, 각 행은 data:로 시작합니다:

data: {"id":"chatcmpl-123","choices":[{"delta":{"content":"안녕"}}]}

data: {"id":"chatcmpl-123","choices":[{"delta":{"content":"하세요"}}]}

data: [DONE]

도구 호출과 JSON 모드

OpenAI 형식으로 tools를 전달하면 모델이 호출할 함수와 인수를 message.tool_calls에 반환합니다. 아래 요청은 테스트에서 get_weather와 {"city": "Paris"}를 반환했습니다.

curl https://api.xhuoapi.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [{"role": "user", "content": "What is the weather in Paris? Use the tool."}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
      }
    }],
    "tool_choice": "auto"
  }'

"response_format": {"type": "json_object"}를 보내면 모델이 유효한 JSON만 반환합니다. 프롬프트에도 JSON으로 답하라고 쓰면 결과가 더 안정적입니다.

curl https://api.xhuoapi.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [{"role": "user", "content": "Return this JSON exactly: {\"ok\": true}"}],
    "response_format": {"type": "json_object"}
  }'

Anthropic Messages 형식

Claude 모델은 Anthropic 요청 형식과 Anthropic SDK로 호출할 수 있습니다. Anthropic SDK로 작성한 기존 코드는 base_url과 키만 바꾸면 됩니다.

POST /v1/messages

두 가지 인증 헤더 모두 검증했습니다: x-api-key: YOUR_API_KEY 또는 Authorization: Bearer YOUR_API_KEY. 예시의 anthropic-version 헤더는 Anthropic SDK가 자동으로 추가합니다.

curl https://api.xhuoapi.ai/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Python (anthropic SDK)

from anthropic import Anthropic

client = Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://api.xhuoapi.ai",
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.content[0].text)

임베딩

요청과 응답 형식은 OpenAI의 /v1/embeddings와 같습니다. text-embedding-3-small은 1536차원 벡터를 반환합니다.

POST /v1/embeddings

curl https://api.xhuoapi.ai/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model": "text-embedding-3-small", "input": "hello"}'

오류 처리

API는 표준 HTTP 상태 코드로 요청 결과를 나타냅니다.

상태 코드	설명
`200`	요청 성공
`400`	잘못된 요청 파라미터
`401`	API 키가 없거나 유효하지 않음
`429`	요청 빈도 초과
`404`	경로가 없음(대개 URL 오타)
`503`	이 모델에 현재 사용 가능한 상위 서비스가 없거나 모델 이름이 없습니다. 잠시 후 다시 시도하거나 다른 모델로 바꾸세요
`500`	서버 내부 오류

오류 응답 예시

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: ...)",
    "type": "new_api_error"
  }
}

error.message 문구는 바뀔 수 있습니다. 메시지 문자열이 아니라 HTTP 상태 코드로 처리하세요.

코드 예제

Python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.xhuoapi.ai/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "안녕하세요"}
    ]
)

print(response.choices[0].message.content)

Node.js

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.xhuoapi.ai/v1'
});

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: '안녕하세요' }]
});

console.log(response.choices[0].message.content);

cURL

curl https://api.xhuoapi.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "안녕하세요"}]
  }'