개발 가이드
빠른 시작
빠른 시작
이 문서는 CLEVI API 키를 발급받고 첫 요청을 보내 응답을 받는 데까지를 다룹니다. 주소 하나와 키 하나로 cip-5.5-im 과 cip-5.5-mm 두 모델을 호출합니다. 요청과 응답은 OpenAI Chat Completions 형식을 따르므로 OpenAI SDK 에서 base_url 과 api_key 두 값만 바꿔 쓸 수 있습니다. curl · Python · TypeScript 예제를 절마다 탭으로 실었습니다.
API 키 발급
키 발급은 CLEVI Cloud 콘솔에서 합니다. 아래 다섯 단계를 순서대로 따르면 요청에 쓸 키 하나를 얻습니다.
- 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
POST /api/services/v1/aiservice/openai/v1/chat/completions
메시지 배열과 모델 이름을 받아 모델이 생성한 메시지 하나를 choices 배열에 담아 돌려줍니다. 전체 주소는 https://platform.clevi.net/api/services/v1/aiservice/openai/v1/chat/completions 입니다. 요청 본문은 application/json 이고, 인증은 Authorization 헤더에 Bearer 키를 넣습니다.
| 이름 | 형식 | 필수 | 설명 |
|---|---|---|---|
| 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/services/v1/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/services/v1/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/services/v1/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": "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/services/v1/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/services/v1/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/services/v1/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 로 넣으면 응답을 여러 조각으로 나눠 받습니다. 각 조각은 data: 로 시작하는 한 줄이고, 본문은 chat.completion.chunk 객체입니다. 마지막 줄은 data: [DONE] 입니다. 아래 Python 과 TypeScript 예제는 앞 절에서 만든 client 를 그대로 씁니다.
curl -N https://platform.clevi.net/api/services/v1/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]오류
실패한 요청은 HTTP 상태 코드로 원인을 알립니다. 아래 표의 대처를 먼저 확인하고, 같은 코드가 반복되면 요청 시각과 보낸 본문을 남겨 두세요.
| 코드 | 뜻 | 대처 |
|---|---|---|
| 400 | 요청 본문이 형식에 맞지 않습니다 | model 과 messages 가 있는지, JSON 이 닫혔는지 확인합니다 |
| 401 | 키가 없거나 유효하지 않습니다 | Authorization 헤더가 Bearer 로 시작하는지, 키 값이 그대로 복사됐는지 확인합니다 |
| 403 | 이 키로 접근할 수 없습니다 | 키를 발급한 워크스페이스와 요청한 모델 이름을 확인합니다 |
| 404 | 경로가 없습니다 | 주소 끝이 /v1/chat/completions 인지 확인합니다 |
| 429 | 짧은 시간에 요청이 몰렸습니다 | 재시도 간격을 두 배씩 늘려 다시 보냅니다 |
| 500 | 서버 쪽 오류입니다 | 같은 요청을 다시 보내고, 반복되면 지원팀에 요청 시각을 전달합니다 |
다음 단계
모델 이름과 매개변수를 바꿔 가며 결과를 비교하는 것은 플레이그라운드에서 합니다. 키를 새로 만들거나 폐기하는 것은 키 관리 화면에서 합니다.