Developer guide
빠른 시작
빠른 시작
Written in 한국어. A version in your language is being prepared.
이 문서는 CLEVI API 키를 발급받아 첫 요청을 보내고 응답을 받는 데까지를 다룹니다. 주소 하나와 키 하나로 cip-5.5-im과 cip-5.5-mm을 호출하며, 요청과 응답은 OpenAI Chat Completions 형식을 따르므로 쓰던 OpenAI SDK에서 base_url과 api_key 두 값만 바꾸면 됩니다. Anthropic SDK용 경로와 임베딩·음성 경로는 API 호출하기 문서에 있습니다.
API 키 발급
키는 CLEVI Cloud 콘솔의 API 키 화면에서 발급합니다. 같은 화면에서 키를 폐기하고 사용 범위를 관리합니다. 아래 순서대로 진행하면 요청에 쓸 키 하나를 얻습니다.
- https://platform.clevi.net/account/login 에서 로그인하거나 계정을 만듭니다.
- https://clevi.app/cloud 에서 워크스페이스를 추가합니다.
- https://clevi.app/cloud/keys 로 이동합니다.
- 새 키를 발급하고 값을 복사합니다.
- 복사한 값을 환경 변수에 저장합니다.
이 문서의 예제에 나오는 sk-... 자리에 발급받은 키를 넣습니다. 아래 명령으로 환경 변수에 저장해 두면 이후 예제를 그대로 복사해 실행할 수 있습니다.
export CLEVI_API_KEY="sk-..."모델 고르기
요청 본문의 model 필드에 아래 이름을 그대로 넣습니다. 두 모델은 같은 주소와 같은 요청 형식을 쓰며, 텍스트와 이미지를 입력으로 받습니다.
- cip-5.5-im
- cip-5.5-mm
| 모델 ID | 규모 | 입력 한도 | 최대 출력 | 맞는 작업 |
|---|---|---|---|---|
| cip-5.5-im | 360B | 256K | 64K | 목표와 범위가 명확한 업무. 응답 속도와 처리량을 우선합니다. |
| cip-5.5-mm | 800B | 512K | 64K | 여러 자료와 조건을 종합하는 복합 업무. 긴 문맥 분석과 다단계 에이전트에 씁니다. |
계정에서 실제로 호출할 수 있는 모델은 플레이그라운드의 모델 목록과 GET /models 응답이 기준입니다. 전체 모델 목록과 모델별 허용된 호출은 모델 문서에, 예상 차감 크레딧은 콘솔의 사용량 화면에 있습니다.
POST /api/v2/aiservice/openai/v1/chat/completions
메시지 배열과 모델 이름을 받아 모델이 생성한 메시지를 choices 배열에 담아 반환합니다. 전체 주소는 https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions 입니다. 요청 본문은 application/json이고, 인증은 Authorization 헤더에 Bearer 접두사와 키를 넣습니다. X-API-Key 헤더로 키를 보내도 되며, 두 헤더를 모두 지정하면 X-API-Key 값이 우선 적용됩니다.
| 이름 | 형식 | 필수 | 설명 |
|---|---|---|---|
| model | string | 예 | cip-5.5-im 또는 cip-5.5-mm |
| messages | array | 예 | 대화 메시지 객체의 배열. 최소 1개 |
| messages[].role | string | 예 | system · user · assistant 중 하나 |
| messages[].content | string | 예 | 메시지 본문 |
| stream | boolean | 아니오 | true이면 응답을 Server-Sent Events 조각으로 나눠 받습니다 |
| max_tokens | integer | 아니오 | 응답으로 생성할 최대 토큰 수 |
| temperature | number | 아니오 | 값이 클수록 같은 요청에서 서로 다른 응답이 나올 확률이 높아집니다 |
curl https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions \
-H "Authorization: Bearer $CLEVI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "cip-5.5-im",
"messages": [
{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}
]
}'import os
import requests
url = "https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions"
response = requests.post(
url,
headers={"Authorization": f"Bearer {os.environ['CLEVI_API_KEY']}"},
json={
"model": "cip-5.5-im",
"messages": [{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}],
},
timeout=60,
)
print(response.json()["choices"][0]["message"]["content"])const url =
"https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions";
const response = await fetch(url, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CLEVI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "cip-5.5-im",
messages: [{ role: "user", content: "CLEVI API를 한 문장으로 설명해 줘." }],
}),
});
const data = await response.json();
console.log(data.choices[0].message.content);응답 예시입니다. id, created, usage 값은 요청마다 다릅니다.
{
"id": "chatcmpl-3f0a9c72",
"object": "chat.completion",
"created": 1755500000,
"model": "cip-5.5-im",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "CLEVI API는 주소 하나로 여러 모델을 호출하는 채팅 완료 API입니다."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 21,
"completion_tokens": 19,
"total_tokens": 40
}
}OpenAI SDK로 호출하기
OpenAI SDK의 base_url을 https://platform.clevi.net/api/v2/aiservice/openai/v1 로 바꾸고 api_key에 CLEVI 키를 넣습니다. 나머지 호출 코드는 그대로 둡니다.
# pip install openai
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["CLEVI_API_KEY"],
base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)
completion = client.chat.completions.create(
model="cip-5.5-mm",
messages=[{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}],
)
print(completion.choices[0].message.content)// npm install openai
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.CLEVI_API_KEY,
baseURL: "https://platform.clevi.net/api/v2/aiservice/openai/v1",
});
const completion = await client.chat.completions.create({
model: "cip-5.5-mm",
messages: [{ role: "user", content: "CLEVI API를 한 문장으로 설명해 줘." }],
});
console.log(completion.choices[0].message.content);스트리밍으로 받기
요청 본문에 stream을 true로 넣으면 서버가 Server-Sent Events로 응답합니다. 첫 조각과 함께 Content-Type: text/event-stream, Cache-Control: no-cache, X-Accel-Buffering: no 헤더가 내려오고, 이후 조각마다 data: 줄에 chat.completion.chunk 객체가 담깁니다. 마지막 줄은 data: [DONE]입니다. 아래 Python과 TypeScript 예제는 앞 절에서 만든 client를 그대로 씁니다.
curl -N https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions \
-H "Authorization: Bearer $CLEVI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "cip-5.5-im",
"messages": [{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}],
"stream": true
}'stream = client.chat.completions.create(
model="cip-5.5-im",
messages=[{"role": "user", "content": "CLEVI API를 한 문장으로 설명해 줘."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="")const stream = await client.chat.completions.create({
model: "cip-5.5-im",
messages: [{ role: "user", content: "CLEVI API를 한 문장으로 설명해 줘." }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}조각 예시입니다.
data: {"id":"chatcmpl-3f0a9c72","object":"chat.completion.chunk","model":"cip-5.5-im","choices":[{"index":0,"delta":{"content":"CLEVI"},"finish_reason":null}]}
data: {"id":"chatcmpl-3f0a9c72","object":"chat.completion.chunk","model":"cip-5.5-im","choices":[{"index":0,"delta":{"content":" API는"},"finish_reason":null}]}
data: {"id":"chatcmpl-3f0a9c72","object":"chat.completion.chunk","model":"cip-5.5-im","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]스트리밍 도중 오류가 나면 같은 오류 JSON이 data: 한 줄로 오고 HTTP 상태 코드도 함께 바뀝니다.
오류
실패한 요청은 HTTP 상태 코드로 원인을 알립니다. 업스트림이 4xx·5xx를 반환하면 그 코드를 그대로 전달합니다. 아래 표의 대처를 먼저 확인하고, 같은 코드가 반복되면 요청 시각, 보낸 본문, X-Request-Id를 남겨 두세요.
| 코드 | 뜻 | 대처 |
|---|---|---|
| 400 | 요청 본문이 형식에 맞지 않습니다 | model과 messages가 있는지, JSON이 닫혔는지 확인합니다 |
| 401 | 키가 없거나 만료·폐기된 키입니다 | API 키 화면에서 키 상태를 확인하고, Authorization 헤더가 Bearer로 시작하는지 점검합니다 |
| 403 | 모델 접근 권한이 없거나, 사용 한도를 넘었거나, 크레딧이 부족합니다 | error.message로 사유를 확인합니다. 한도는 개요의 할당된 사용 한도에서, 잔액과 플랜은 플랜과 크레딧에서 봅니다 |
| 404 | 모델이 없거나 이 키로 접근할 수 없거나, 경로가 없습니다 | GET /models 응답에 모델 이름이 있는지, 주소가 /api/v2/aiservice/openai/v1/chat/completions로 끝나는지 확인합니다 |
| 429 | 업스트림 제공자가 속도 제한을 걸었습니다 | Retry-After 헤더가 있으면 그 시간만큼 기다리고, 없으면 재시도 간격을 두 배씩 늘려 다시 보냅니다 |
| 5xx | 게이트웨이 또는 업스트림의 일시적 오류입니다 | 재시도 간격을 두 배씩 늘려 다시 보내고, 반복되면 도움말과 문의로 X-Request-Id와 함께 알립니다 |
402는 반환하지 않습니다. 크레딧 부족과 사용 한도 초과는 403으로 옵니다. 오류 본문은 아래 형식이며 error.message에 사유가 담깁니다.
{"error":{"message":"API key is required.","type":"invalid_request_error"}}요청에 X-Request-Id 헤더를 넣어 두면 문의할 때 그 값으로 추적합니다. 보내지 않으면 서버가 발급합니다.
다음 단계
모델 이름과 매개변수를 바꿔 가며 결과를 비교하는 것은 플레이그라운드에서 합니다. 키를 새로 만들거나 폐기하는 것은 API 키 화면에서 합니다. 이어서 읽을 문서는 다음과 같습니다.
- 모델: 전체 모델 목록과 모델별 사양, 허용된 호출
- API 호출하기: Anthropic 호환 경로, 임베딩·음성 경로, 스트리밍 규칙
- 오류 코드: 전체 상태 코드 표와 재시도 규칙