AI/AI AGENT

Moonshot AI API 완전 매뉴얼 가이드

dma-ai 2025. 7. 15. 16:09
728x90

Moonshot AI API 완전 매뉴얼 가이드

Moonshot AI는 중국 베이징에 본사를 둔 AI 스타트업으로, 오픈소스 정신을 바탕으로 개발한 강력한 언어 모델 API 서비스를 제공합니다^1. 이 가이드는 Moonshot AI API를 처음 사용하는 개발자부터 고급 사용자까지 모두를 위한 완전한 매뉴얼입니다.

🚀 시작하기

Moonshot AI API란?

Moonshot AI API는 OpenAI SDK와 완전히 호환되는 텍스트 생성 API 서비스입니다^2. 특히 긴 컨텍스트 처리에 특화되어 있으며, 최대 200만 개의 중국어 문자를 한 번에 처리할 수 있는 능력을 갖추고 있습니다^1.

주요 특징

  • OpenAI SDK 호환성: 기존 OpenAI 코드를 거의 수정 없이 사용 가능^2
  • 긴 컨텍스트 지원: 최대 128K 토큰 처리 가능^2
  • 다양한 모델 옵션: 8K, 32K, 128K 컨텍스트 모델 제공^3
  • 도구 호출 지원: Function calling 기능 제공^4
  • 파일 처리: 문서 업로드 및 분석 기능^5

🔑 API 키 발급 방법

1단계: 계정 등록

  1. Moonshot AI 플랫폼 접속: https://platform.moonshot.ai 또는 https://platform.moonshot.cn[^3]
  2. 우측 상단 "Sign Up" 버튼 클릭하여 회원가입
  3. 이메일 인증 완료

2단계: API 키 생성

  1. 로그인 후 "사용자센터 → API Key Management" 메뉴 진입^3
  2. "Create new secret key" 버튼 클릭^6
  3. 키 이름 및 프로젝트 설정
  4. 생성된 API 키 복사 및 안전한 곳에 저장

⚠️ 중요: API 키는 한 번만 표시되므로 생성 즉시 반드시 복사하여 저장해야 합니다^6.

📋 지원 모델

Moonshot AI는 컨텍스트 길이에 따라 세 가지 모델을 제공합니다^3:

모델명 최대 컨텍스트 가격 (100만 토큰)
moonshot-v1-8k 8,192 토큰 12.00원
moonshot-v1-32k 32,768 토큰 24.00원
moonshot-v1-128k 131,072 토큰 60.00원

🔌 API 엔드포인트

기본 정보

주요 엔드포인트

  1. 채팅 완료: /v1/chat/completions^2
  2. 파일 업로드: /v1/files^5
  3. 파일 추출: /v1/files/extract^5
  4. 모델 목록: /v1/models

💻 사용 예제

Python 예제

from openai import OpenAI

# 클라이언트 초기화
client = OpenAI(
    api_key="YOUR_MOONSHOT_API_KEY",  # API 키 입력
    base_url="https://api.moonshot.cn/v1"
)

# 기본 채팅 요청
completion = client.chat.completions.create(
    model="moonshot-v1-8k",
    messages=[
        {
            "role": "system", 
            "content": "당신은 도움이 되는 AI 어시스턴트입니다."
        },
        {
            "role": "user", 
            "content": "안녕하세요, 파이썬에 대해 설명해주세요."
        }
    ],
    temperature=0.3
)

print(completion.choices[^0].message.content)

Node.js 예제

const OpenAI = require('openai');

const client = new OpenAI({
    apiKey: 'YOUR_MOONSHOT_API_KEY',
    baseURL: 'https://api.moonshot.cn/v1'
});

async function chatCompletion() {
    try {
        const completion = await client.chat.completions.create({
            model: 'moonshot-v1-8k',
            messages: [
                {
                    role: 'system',
                    content: '당신은 도움이 되는 AI 어시스턴트입니다.'
                },
                {
                    role: 'user',
                    content: '안녕하세요, JavaScript에 대해 설명해주세요.'
                }
            ],
            temperature: 0.3
        });

        console.log(completion.choices[^0].message.content);
    } catch (error) {
        console.error('Error:', error);
    }
}

chatCompletion();

cURL 예제

curl -X POST https://api.moonshot.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_MOONSHOT_API_KEY" \
  -d '{
    "model": "moonshot-v1-8k",
    "messages": [
      {
        "role": "system",
        "content": "당신은 도움이 되는 AI 어시스턴트입니다."
      },
      {
        "role": "user",
        "content": "안녕하세요, REST API에 대해 설명해주세요."
      }
    ],
    "temperature": 0.3
  }'

스트리밍 예제

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_MOONSHOT_API_KEY",
    base_url="https://api.moonshot.cn/v1"
)

# 스트리밍 요청
stream = client.chat.completions.create(
    model="moonshot-v1-8k",
    messages=[
        {"role": "user", "content": "긴 이야기를 들려주세요."}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[^0].delta.content is not None:
        print(chunk.choices[^0].delta.content, end="")

🔧 도구 호출 (Tool Calls)

Moonshot AI는 외부 도구를 호출할 수 있는 기능을 제공합니다^4:

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_web",
            "description": "웹에서 정보를 검색합니다.",
            "parameters": {
                "type": "object",
                "required": ["query"],
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "검색할 내용"
                    }
                }
            }
        }
    }
]

completion = client.chat.completions.create(
    model="moonshot-v1-8k",
    messages=[
        {"role": "user", "content": "최신 AI 뉴스를 찾아주세요."}
    ],
    tools=tools
)

📁 파일 처리

파일 업로드

# 파일 업로드
with open("document.txt", "rb") as file:
    file_object = client.files.create(
        file=file,
        purpose="file-extract"
    )

# 파일 내용 추출
extracted_content = client.files.retrieve_content(file_object.id)

💰 가격 정보

토큰 기반 과금

모델 100만 토큰당 가격
moonshot-v1-8k 12.00원
moonshot-v1-32k 24.00원
moonshot-v1-128k 60.00원

무료 크레딧

  • 신규 사용자: 15원 상당 무료 토큰 제공^7
  • 테스트 및 개발 용도로 충분한 양

📊 사용 제한

계정 등급별 제한

등급 누적 충전 동시 요청 RPM TPM TPD
무료 0원 1 3 32K 1.5M
1등급 50원 50 200 128K 10M
2등급 100원 100 500 128K 20M
3등급 500원 200 5K 384K 무제한
4등급 5,000원 400 5K 768K 무제한
5등급 20,000원 1,000 10K 2M 무제한

RPM: 분당 요청 수, TPM: 분당 토큰 수, TPD: 일일 토큰 수

🔒 보안 및 모범 사례

API 키 관리

# 환경 변수 설정 (.env 파일)
MOONSHOT_API_KEY=your_api_key_here
import os
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(
    api_key=os.getenv("MOONSHOT_API_KEY"),
    base_url="https://api.moonshot.cn/v1"
)

보안 주의사항

  • API 키를 코드에 하드코딩하지 않기
  • 환경 변수 또는 보안 저장소 사용
  • Git 리포지토리에 API 키 업로드 금지
  • 정기적인 API 키 교체

🚨 문제 해결

일반적인 오류

  1. 인증 오류 (401)
    • API 키 확인
    • 올바른 헤더 형식 사용: Authorization: Bearer YOUR_API_KEY
  2. 모델 오류 (404)
    • 지원되는 모델명 확인: moonshot-v1-8k, moonshot-v1-32k, moonshot-v1-128k
  3. 사용량 한도 초과 (429)
    • 요청 빈도 조절
    • 계정 등급 업그레이드 고려

디버깅 팁

try:
    completion = client.chat.completions.create(
        model="moonshot-v1-8k",
        messages=[{"role": "user", "content": "테스트"}]
    )
except Exception as e:
    print(f"오류 발생: {e}")
    print(f"오류 타입: {type(e)}")

📚 추가 리소스

공식 문서

커뮤니티

🎯 결론

Moonshot AI API는 긴 컨텍스트 처리와 OpenAI 호환성을 제공하는 강력한 도구입니다. 이 매뉴얼을 통해 API 키 발급부터 고급 기능 활용까지 모든 과정을 마스터할 수 있습니다.

특히 대용량 텍스트 처리나 복잡한 문서 분석이 필요한 프로젝트에서 Moonshot AI의 진가를 발휘할 수 있습니다. 무료 크레딧을 활용하여 먼저 테스트해보고, 프로젝트 요구사항에 맞는 모델을 선택하시기 바랍니다.

⁂
728x90
저작자표시 변경금지 (새창열림)