공식 SDK 지원

MoleAPI는 주요 OpenAI 스타일 SDK와 호환됩니다. 일반적으로 다음 두 가지만 교체하면 됩니다.

apiKey
baseURL

언제 SDK를 직접 사용하는 것이 적합한가요

아래 시나리오 중 하나라도 해당한다면, 보통은 직접 HTTP 요청을 조합하기보다 공식 SDK를 우선 사용하는 것이 좋습니다.

이미 Python / Node.js로 서비스를 개발하고 있는 경우
이후 스트리밍 출력, 이미지, 오디오 또는 도구 호출까지 연동할 예정인 경우
하위 레벨 요청 세부 사항은 최소화하고, 우선 기능을 빠르게 동작시키고 싶은 경우

간단한 판단 기준

계정이 사용 가능한지만 확인하려면 먼저 cURL을 사용하세요. 기능을 프로젝트에 연동할 계획이라면 SDK를 바로 사용하는 것이 좋습니다.

Python 예제

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["MOLEAPI_KEY"],
    base_url="https://api.moleapi.com/v1",
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "用一句话说明 SDK 接入要点"}],
)

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

아직 환경 변수를 설정하지 않았다면, 현재 터미널에서 먼저 다음을 실행할 수 있습니다.

$env:MOLEAPI_KEY="sk-xxxxxxxxxxxxxxxx"

Node.js 예제

import OpenAI from "openai";

async function main() {
  const client = new OpenAI({
    apiKey: process.env.MOLEAPI_KEY,
    baseURL: "https://api.moleapi.com/v1",
  });

  const res = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Hello MoleAPI" }],
  });

  console.log(res.choices[0]?.message?.content);
}

main().catch(console.error);

Node.js에서도 마찬가지로 환경 변수를 통해 Key를 읽는 것을 권장하며, 실제 비밀 키를 소스 코드에 직접 작성하거나 리포지토리에 커밋하지 마세요.

가장 흔한 호환성 문제

baseURL을 다른 플랫폼 주소로 작성했거나 /v1이 누락된 경우
환경 변수가 정상적으로 주입되지 않아 요청 시 실제로는 빈 값을 가져오는 경우
예제를 복사하는 과정에서 호환되지 않는 모델명이나 파라미터까지 함께 가져온 경우
로컬에서는 동작하지만 배포 환경에 동일한 Key와 Base URL이 동기화되지 않은 경우

권장 연동 순서

먼저 가장 짧은 예제로 한 번 정상 동작시키기
그다음 실제 서비스에서 사용할 모델로 교체하기
마지막으로 스트리밍 출력, Retry, 타임아웃, 로그를 연동하기

이렇게 하면 문제를 가장 쉽게 파악할 수 있습니다. 현재 이슈가 "플랫폼 연동이 아직 되지 않은 것"인지, 아니면 "서비스의 복잡한 로직이 새로운 문제를 유입한 것"인지 명확하게 구분할 수 있기 때문입니다.

일반적인 문제 해결

401 오류: 먼저 API Key와 환경 변수를 확인하세요
404 오류: 우선 baseURL에 /v1이 포함되어 있는지 확인하세요
모델을 사용할 수 없다는 오류: Group 및 모델 권한을 확인하세요