Documentation
API 문서
칩섭 AI 사용 방법을 안내합니다. OpenAI SDK와 호환됩니다.
빠른 시작
칩섭 AI는 OpenAI SDK와 호환됩니다. base_url과 API 키만 변경하면 기존 코드를 그대로 사용할 수 있습니다.
# Base URL
https://api.cheapsub.im
# Authorization Header
Authorization: Bearer csk_발급받은_API_키
엔드포인트
| 메서드 | 경로 | 설명 |
|---|---|---|
| POST | /api/v1/chat | 채팅 (GPT, Gemini, Claude 통합) |
| POST | /api/v1/image | 이미지 생성 |
| POST | /api/v1/video | 비디오 생성 (Sora, Veo) |
| GET | /api/v1/task | 비동기 태스크 상태 조회 |
| GET | /api/v1/models | 지원 모델 목록 |
채팅 (Chat Completions)
GPT, Gemini, Claude 모든 모델을 동일한 인터페이스로 호출합니다.
Python (OpenAI SDK)
from openai import OpenAI
client = OpenAI(
api_key="csk_YOUR_API_KEY",
base_url="https://api.cheapsub.im/api/v1"
)
response = client.chat.completions.create(
model="gemini-3-flash",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "한국의 수도는 어디인가요?"}
]
)
print(response.choices[0].message.content)cURL
curl -X POST https://api.cheapsub.im/api/v1/chat \
-H "Authorization: Bearer csk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-flash",
"messages": [
{"role": "user", "content": "안녕하세요!"}
]
}'Node.js (fetch)
const response = await fetch("https://api.cheapsub.im/api/v1/chat", {
method: "POST",
headers: {
"Authorization": "Bearer csk_YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "gemini-3-flash",
messages: [{ role: "user", content: "Hello!" }]
})
});
const data = await response.json();
console.log(data.choices[0].message.content);스트리밍
stream = client.chat.completions.create(
model="gemini-3-flash",
messages=[{"role": "user", "content": "Tell me a story."}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")요청 파라미터
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| model | string | ✅ | 모델 ID |
| messages | array | ✅ | 대화 메시지 목록 |
| stream | boolean | ❌ | SSE 스트리밍 |
| temperature | number | ❌ | 0.0 ~ 2.0 |
| max_tokens | number | ❌ | 최대 출력 토큰 수 |
이미지 생성
텍스트 프롬프트로 이미지를 생성합니다. 비동기 방식으로 task_id를 반환합니다.
cURL
curl -X POST https://api.cheapsub.im/api/v1/image \
-H "Authorization: Bearer csk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nano-banana-2",
"prompt": "A cute cat sitting on a windowsill watching the rain",
"aspect_ratio": "16:9",
"image_size": "2k"
}'Python
import requests
response = requests.post(
"https://api.cheapsub.im/api/v1/image",
headers={
"Authorization": "Bearer csk_YOUR_API_KEY",
"Content-Type": "application/json"
},
json={
"model": "nano-banana-2",
"prompt": "서울 남산타워의 야경, 포토리얼리스틱",
"aspect_ratio": "16:9",
"image_size": "2k"
}
)
data = response.json()
task_id = data["data"]["task_id"]
print(f"Task ID: {task_id}")태스크 완료 시 결과
{
"code": 0,
"data": {
"task_id": "tadaafec-...",
"status": "success",
"result": [
{ "image": "https://google.datas.systems/fileSystem/..." }
],
"consumed": "0.500000"
}
}result[].image는 URL 또는 data:image/png;base64,... 형식
요청 파라미터
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| model | string | ✅ | nano-banana-2, nano-banana-pro, nano-banana |
| prompt | string | ✅ | 이미지 설명 |
| images | string[] | ❌ | 참조 이미지 URL (최대 4개) |
| aspect_ratio | string | ❌ | 1:1, 16:9, 9:16, 4:3, 3:4 |
| image_size | string | ❌ | 1k / 2k / 4k (nano-banana-pro, nano-banana-2 전용) |
| callback_url | string | ❌ | 완료 콜백 수신 URL |
| failed_if_no_image | boolean | ❌ | 필터링 시 실패 처리 여부 |
비디오 생성
비동기 방식입니다. 요청 후 task_id를 받고, 완료될 때까지 상태를 조회합니다.
cURL — 비디오 생성 요청
curl -X POST https://api.cheapsub.im/api/v1/video \
-H "Authorization: Bearer csk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "sora-2",
"prompt": "A golden retriever running on a beach at sunset",
"duration": "10"
}'cURL — 상태 조회
curl "https://api.cheapsub.im/api/v1/task?task_id=abc123-def456" \ -H "Authorization: Bearer csk_YOUR_API_KEY"
Python (생성 + 폴링)
import requests, time
API_KEY = "csk_YOUR_API_KEY"
BASE = "https://api.cheapsub.im"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
# 1. 비디오 생성 요청
res = requests.post(f"{BASE}/api/v1/video", headers=HEADERS, json={
"model": "sora-2",
"prompt": "A cat playing piano in a jazz club",
"duration": "10"
})
task_id = res.json().get("task_id")
# 2. 완료 대기
while True:
status = requests.get(f"{BASE}/api/v1/task?task_id={task_id}", headers=HEADERS).json()
print(f"Status: {status.get('status')}")
if status.get("status") in ("completed", "failed"):
print(status)
break
time.sleep(10)요청 파라미터
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| model | string | ✅ | sora-2 |
| prompt | string | ✅ | 비디오 설명 |
| duration | string | ❌ | "10" | "15" | "25" (기본 "10") |
| resolution | string | ❌ | 720p, 1080p |
지원 모델
💬 언어 모델 (Chat)
| 모델 ID | 설명 |
|---|---|
| gemini-3.1-pro-preview | Google Gemini 3.1 Pro |
| gemini-3-pro-thinking | Google Gemini 3 Pro Thinking |
| gemini-3-pro | Google Gemini 3 Pro |
| gemini-3-flash-thinking | Google Gemini 3 Flash Thinking |
| gemini-3-flash | Google Gemini 3 Flash |
| claude-sonnet-4.6 | Anthropic Claude Sonnet 4.6 |
| claude-opus-4.6 | Anthropic Claude Opus 4.6 |
| claude-haiku-4.5-thinking | Anthropic Claude Haiku 4.5 Thinking |
| claude-haiku-4.5 | Anthropic Claude Haiku 4.5 |
| claude-opus-4.5 | Anthropic Claude Opus 4.5 |
| claude-sonnet-4.5 | Anthropic Claude Sonnet 4.5 |
| gpt-5.4 | OpenAI GPT 5.4 |
| gpt-5.2 | OpenAI GPT 5.2 |
🖼️ 이미지 모델
• nano-banana-2 — Google Nano Banana 2
• nano-banana-pro — Google Nano Banana Pro
• nano-banana — Google Nano Banana
• gpt-image-1.5 — OpenAI GPT Image 1.5
🎬 비디오 모델
• sora-2 — OpenAI Sora 2
• sora-2-stable — OpenAI Sora 2 Stable
• sora-2-pro — OpenAI Sora 2 Pro
• veo3-fast — Google Veo 3 Fast
• veo3-pro — Google Veo 3 Pro
• veo3.1 — Google Veo 3.1
• veo3.1-fast — Google Veo 3.1 Fast
• veo3.1-components — Google Veo 3.1 Components
과금 방식
• 1원 = 1크레딧 구조입니다.
• 입력 토큰과 출력 토큰에 따라 크레딧이 차감됩니다.
• 실시간 USD/KRW 환율이 반영됩니다.
• 이미지/비디오 생성은 작업 단위 과금됩니다.
• 모델별 상세 단가는 모델 카탈로그를 참고하세요.
에러 코드
| 코드 | 상태 | 설명 |
|---|---|---|
| 401 | UNAUTHENTICATED | API 키 누락 |
| 403 | PERMISSION_DENIED | 유효하지 않거나 비활성 API 키 |
| 404 | NOT_FOUND | 알 수 없는 엔드포인트 |
| 502 | BAD_GATEWAY | 업스트림 서버 에러 |
| 504 | GATEWAY_TIMEOUT | 업스트림 타임아웃 |
레거시 엔드포인트
기존 Gemini/Claude 네이티브 API 형식도 지원합니다.
• /api/v1beta/models/{model}:generateContent — Gemini 네이티브
• /api/v1beta/models/{model}:streamGenerateContent — Gemini 스트리밍
• /api/v1/messages — Claude 네이티브
• /api/image/gen — 이미지 생성
• /api/sora2/gen — Sora 비디오 생성
• /api/google/veo/generate — Veo 비디오 생성
• /api/task/query?task_id={id} — 태스크 조회
OpenAI SDK 호환
base_url을 https://api.cheapsub.im/api/v1로 설정하면 기존 OpenAI Python/Node.js SDK를 그대로 사용할 수 있습니다.
AI에게 https://cheapsub.im/docs.md 주소를 전달하면 바로 코드를 생성할 수 있습니다.