문서
MAX API API 연동에 필요한 모든 것.
빠른 시작
MAX API API는 OpenAI API와 호환됩니다. 이미 OpenAI SDK를 사용 중이라면 Base URL과 API 키 두 가지만 바꾸면 됩니다.
인증
모든 요청의 Authorization 헤더에 API 키를 넣어 인증하세요. 키는 비밀로 유지하고 브라우저나 모바일 앱에 노출하지 마세요.
Authorization: Bearer YOUR_API_KEY채팅 완성
메시지 목록을 보내고 모델의 응답을 받습니다. 카탈로그의 모든 채팅 모델 ID를 사용할 수 있습니다.
curl https://clubs.byte-ai.cn/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-terra",
"messages": [{"role": "user", "content": "Hello!"}]
}'스트리밍
stream을 true로 설정하면 생성되는 토큰을 Server-Sent Events(SSE)로 실시간 수신합니다. 스트림은 data: [DONE]으로 끝납니다.
curl https://clubs.byte-ai.cn/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-terra",
"messages": [{"role": "user", "content": "Hello!"}],
"stream": true
}'이미지 생성
Images API로 이미지를 생성합니다. 카탈로그에서 이미지 모델을 선택하세요.
curl https://clubs.byte-ai.cn/v1/images/generations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-1",
"prompt": "A lighthouse on a cliff at sunset, watercolor",
"size": "1024x1024"
}'Anthropic 형식
Claude 모델은 /v1/messages에서 Anthropic 네이티브 Messages 형식으로도 호출할 수 있으며, x-api-key 헤더를 사용합니다(Authorization 헤더도 가능). 공식 Anthropic SDK를 그대로 사용할 수 있습니다.
curl https://clubs.byte-ai.cn/v1/messages \
-H "x-api-key: $API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello!"}]
}'모델 목록
키로 사용할 수 있는 모델 목록을 조회합니다.
curl https://clubs.byte-ai.cn/v1/models \
-H "Authorization: Bearer $API_KEY"오류 코드
오류는 표준 HTTP 상태 코드와 OpenAI 형식의 JSON으로 반환됩니다:
{
"error": {
"message": "Invalid API key",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}| 상태 코드 | 의미 |
|---|---|
| 400 | 잘못된 요청: 매개변수가 유효하지 않거나 JSON 형식이 잘못되었습니다. |
| 401 | API 키가 유효하지 않거나 누락되었습니다. |
| 403 | 잔액이 부족하거나 이 키로 해당 모델을 사용할 수 없습니다. |
| 404 | 존재하지 않는 엔드포인트이거나 사용할 수 없는 모델입니다. |
| 429 | 요청이 너무 많습니다. 속도를 줄이고 백오프 후 재시도하세요. |
| 500 | 내부 오류: 재시도해도 안전합니다. |
| 502 / 503 | 업스트림을 일시적으로 사용할 수 없습니다. 잠시 후 재시도하세요. |
요청 한도
기본 한도는 프로덕션 워크로드에 충분하도록 넉넉하게 설정되어 있습니다. 한도를 초과하면 429가 반환되니 지수 백오프로 재시도하세요. 더 높은 처리량이 필요하면 콘솔을 통해 문의해 주세요.
추론 모델의 긴 생성은 몇 분이 걸릴 수 있습니다. 클라이언트 타임아웃을 300초 이상으로 설정하거나 스트리밍을 사용하세요.
자주 묻는 질문
어떤 SDK를 지원하나요?+
OpenAI 호환 SDK나 HTTP 클라이언트라면 모두 사용할 수 있습니다: 공식 OpenAI SDK(Python / Node.js), LangChain, LlamaIndex 등. Claude 모델은 Anthropic SDK도 사용할 수 있습니다.
함수 호출과 JSON 출력을 지원하나요?+
네, 해당 기능을 지원하는 모델이라면 사용할 수 있습니다. tools, tool_choice, response_format 등의 매개변수는 모델에 그대로 전달됩니다.
하나의 키로 모든 모델을 호출할 수 있나요?+
네. 하나의 API 키로 카탈로그의 모든 모델을 사용할 수 있으며, 모델별 공식 가격으로 과금됩니다.
모델은 어떻게 바꾸나요?+
요청의 model 필드만 바꾸면 됩니다. 다른 변경은 필요 없습니다.