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단계: 계정 등록

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

2단계: API 키 생성

로그인 후 "사용자센터 → API Key Management" 메뉴 진입^3
"Create new secret key" 버튼 클릭^6
키 이름 및 프로젝트 설정
생성된 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 엔드포인트

기본 정보

기본 URL: https://api.moonshot.cn/v1[^2]
인증 방식: Bearer Token
요청 형식: JSON
응답 형식: JSON

주요 엔드포인트

채팅 완료: /v1/chat/completions^2
파일 업로드: /v1/files^5
파일 추출: /v1/files/extract^5
모델 목록: /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 키 교체

🚨 문제 해결

일반적인 오류

인증 오류 (401)
- API 키 확인
- 올바른 헤더 형식 사용: Authorization: Bearer YOUR_API_KEY
모델 오류 (404)
- 지원되는 모델명 확인: moonshot-v1-8k, moonshot-v1-32k, moonshot-v1-128k
사용량 한도 초과 (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)}")

📚 추가 리소스

공식 문서

플랫폼: https://platform.moonshot.ai
API 문서: https://platform.moonshot.ai/docs/api/chat
GitHub: https://github.com/moonshotai

커뮤니티

Hugging Face: https://huggingface.co/moonshotai
OpenRouter: 대안 API 접근 방법 제공

🎯 결론

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

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

⁂

728x90

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

'AI > AI AGENT' 카테고리의 다른 글

Ubuntu에서 Node.js® v24.3.0 및 Claude Code 설치 메뉴얼 (0)	2025.06.30
Replit 사용 매뉴얼: 초보자를 위한 가이드 (1)	2025.06.22
Claude Task Master: AI 기반 태스크 관리 시스템 완벽 가이드 (0)	2025.05.18
Claude Code 설치 및 인증 완벽 가이드: 시스템 오류 방지 팁 포함 [2025년 최신] (0)	2025.03.20
Browser Use 완벽 가이드: AI로 웹 브라우저 자동화하기 (2)	2025.03.19

dma-ai

AI Insights & Innovations