한 눈에 보기

이 문서는 CLEVI 개발자 문서의 시작점입니다. Clevi-X-Platform 의 구성, API 로 호출할 수 있는 모델 두 가지, 인증 방식, 요청과 응답 형식을 한 번에 정리합니다. 요청과 응답은 OpenAI Chat Completions 형식을 따르므로 기존 OpenAI SDK 에서 base_url 과 api_key 두 값만 바꿔 연결합니다. 설치 없이 첫 호출까지 따라가는 절차는 Quick Start 문서에 있습니다.

플랫폼 구성

Clevi-X-Platform 은 모델, 에이전트, 시맨틱 데이터베이스, 물리 AI 를 하나의 실행 환경에 둡니다. 이 가운데 개발자가 지금 HTTP 로 직접 호출하는 것은 모델 계층입니다. 나머지 계층은 플랫폼 내부와 콘솔에서 동작하며, 공개 API 는 아래 표에 표시된 범위까지입니다.

모델 라인업

요청 본문의 model 필드에 아래 두 이름 중 하나를 그대로 넣습니다. 두 모델은 같은 주소, 같은 인증, 같은 요청 형식을 씁니다.

• cip-5.5-im
• cip-5.5-mm

cip-5.5-im

문서, 이미지, 도면, 업무 데이터를 의미 단위로 연결해 검색 결과와 지식 구조를 만듭니다. Physical AI 의 계획 수립과 재계획 단계에서 입력을 해석하는 데도 같은 모델을 씁니다. 내부 식별자로 RB-IM 이 쓰이며, API 에서는 cip-5.5-im 만 유효한 이름입니다.

cip-5.5-mm

텍스트와 이미지, 그리고 여러 문서에 걸친 복합 문맥을 함께 읽고 답을 만듭니다. 도구 호출과 업무 흐름 실행을 포함하는 Agentic 작업에 맞춰 조정된 모델입니다.

모델 고르기

그 밖의 모델

플랫폼에는 아래 모델이 함께 있습니다. 배포 형태와 접근 경로가 서로 달라, 공개 API 이름은 별도로 안내합니다.

기본 정보와 인증

키는 워크스페이스 단위로 발급하고, 요청마다 Authorization 헤더에 Bearer 로 붙입니다. 아래 표의 값 여섯 개면 첫 호출에 필요한 설정이 끝납니다.

표와 예제의 sk-... 는 발급받은 키를 넣는 자리입니다. 아래 명령으로 환경 변수에 넣어 두면 이 문서의 예제를 그대로 복사해 실행할 수 있습니다.

export CLEVI_API_KEY="sk-..."

POST /api/services/v1/aiservice/openai/v1/chat/completions

메시지 배열과 모델 이름을 받아 모델이 생성한 메시지 하나를 choices 배열에 담아 돌려줍니다. 전체 주소는 https://platform.clevi.net/api/services/v1/aiservice/openai/v1/chat/completions 입니다. messages 는 최소 1개의 메시지 객체를 포함해야 하고, 각 객체는 role 과 content 를 가집니다.

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-mm",
    "messages": [
      {"role": "system", "content": "사내 문서를 요약하는 도우미로 답한다."},
      {"role": "user", "content": "이 API 의 인증 방식을 한 문장으로 설명해 줘."}
    ]
  }'

# 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": "system", "content": "사내 문서를 요약하는 도우미로 답한다."},
        {"role": "user", "content": "이 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: "system", content: "사내 문서를 요약하는 도우미로 답한다." },
    { role: "user", content: "이 API 의 인증 방식을 한 문장으로 설명해 줘." },
  ],
});

console.log(completion.choices[0].message.content);

{
  "id": "chatcmpl-7d21b4e0",
  "object": "chat.completion",
  "created": 1755500000,
  "model": "cip-5.5-mm",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Authorization 헤더에 Bearer 와 발급받은 API 키를 넣어 인증합니다."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 38,
    "completion_tokens": 24,
    "total_tokens": 62
  }
}

응답 필드

응답은 최상위 필드 여섯 개로 구성됩니다. 생성된 문장은 choices 배열의 첫 원소 안에 있고, 토큰 사용량은 usage 에 있습니다.

오류

실패한 요청은 HTTP 상태 코드로 원인을 알립니다. 아래 대처를 먼저 확인하고, 같은 코드가 반복되면 응답의 id 와 요청 시각을 남겨 두세요.

배포 형태

같은 모델을 클라우드 API 와 온프레미스 설치 두 가지로 씁니다. 요청 형식과 인증 방식은 두 경우가 같고, 주소와 키 관리 화면이 다릅니다.

데이터 거버넌스

플랫폼은 아래 네 가지를 기본 동작으로 둡니다. 워크스페이스를 나누는 기준을 정할 때 함께 확인하세요.

• 권한 기반 통제 — 워크스페이스 단위로 접근 권한과 키를 나눕니다.
• 격리 작업공간 — 워크스페이스 사이에 데이터가 섞이지 않습니다.
• 실시간 데이터 연결 — 외부 시스템과 연결한 데이터를 조회 시점에 가져옵니다.
• 프로세스별 기록 보관 — 실행한 작업 단위로 기록을 남깁니다.

시작 순서

처음 연결한다면 아래 순서로 진행하세요. 3번까지 마치면 키 하나로 두 모델을 모두 호출할 수 있습니다.

1. https://platform.clevi.net/account/login 에서 로그인하거나 계정을 만듭니다.
2. https://clevi.app/cloud 에서 워크스페이스를 추가합니다.
3. https://clevi.app/cloud/keys 에서 키를 발급하고 환경 변수에 저장합니다.
4. https://clevi.app/cloud/playground 에서 cip-5.5-im 과 cip-5.5-mm 의 응답을 비교합니다.
5. Quick Start 문서의 요청 예제를 복사해 첫 호출을 보냅니다.

워크스페이스 만들기

API 키 발급

플레이그라운드 열기