Developer guide
개요
한 눈에 보기
Written in 한국어. A version in your language is being prepared.
CLEVI 모델은 게이트웨이의 API 키 하나로 호출합니다. 요청의 model에 넣을 ID를 고르려면 제품군과 모델별 허용된 호출을, 어느 SDK로 붙일지 정하려면 두 호환 규격의 base URL을 알아야 합니다.
이 문서는 그 두 결정에 필요한 구성 요소, 용어, 제품군, 호출 경로, 콘솔 화면을 정리합니다.
첫 호출 절차는 빠른 시작 문서에 있습니다.
구성 요소
| 구성 요소 | 하는 일 | 자세한 문서 |
|---|---|---|
| 모델 제품군 | CIP는 범용 지능과 업무 자동화, Cosa는 음성 생성과 인식, Cova는 문서와 이미지의 정보 추출을 담당합니다. 게이트웨이의 플랜 표에는 임베딩과 대화형 추론을 맡는 Ivy도 있습니다. | 모델 |
| 게이트웨이 | platform.clevi.net 아래의 API 진입점입니다. OpenAI 호환 경로와 Anthropic 호환 경로로 모델을 호출하며, 두 경로 모두 API 키 하나로 인증합니다. | API 키로 인증하기, API 호출하기 |
| 콘솔 | API 키를 발급·폐기하고, 플레이그라운드에서 모델을 호출하며, 사용량과 한도를 확인합니다. | 아래 콘솔 화면 절 |
| CleviDrive | 음성 합성 경로의 산출물을 저장합니다. 보존 기간은 3일이고 이후에는 404입니다. | API 호출하기 |
용어
| 용어 | 뜻 |
|---|---|
| 게이트웨이 | platform.clevi.net 아래의 API 진입점입니다. OpenAI 호환 경로와 Anthropic 호환 경로를 제공합니다. |
| 호환 규격 | 쓰던 OpenAI SDK 또는 Anthropic SDK의 base URL만 바꿔 쓰도록 맞춘 요청·응답 형식입니다. |
| 워크스페이스 | 한도가 적용되는 단위입니다. 한도 수치는 워크스페이스마다 다릅니다. |
| 플랜 | 모델마다 허용된 호출을 정합니다. LLM_FREE·TTS_FREE·STT_FREE는 신청 없이 자동으로 적용됩니다. |
| 허용된 호출 | 플랜이 모델에 여는 호출 키입니다. chat.completions, anthropic.messages, embeddings, audio.speech 같은 값입니다. |
| Product | 음성·보이스 경로에서 과금에 쓰는 단위입니다. audio/speech와 audio/transcriptions는 본문의 model로, 보이스 경로는 X-Product-Sku 헤더 또는 product_sku 쿼리로 지정합니다. |
제품군과 모델
| 제품군 | 모델 ID | 주된 역할 | 근거 플랜 |
|---|---|---|---|
| CIP | cip-5.5-im | 범용 업무 처리. 응답 속도와 처리량 우선. 360B · 입력 256K · 출력 64K · 멀티모달 | LLM_FREE |
| CIP | cip-5.5-mm | 긴 문맥 분석과 복합 문제 해결. 800B · 입력 512K · 출력 64K · 멀티모달 | LLM_FREE |
| CIP | cip-5.5-sm | 엣지 서버와 로컬 업무 자동화. 24B~40B 조정형 | |
| Cosa | cosa-a, cosa-b | 음성 합성·복제·디자인·스트리밍 | TTS_FREE |
| Cosa | cosa-asr | 음성 인식 | STT_FREE |
| Ivy | ivy-4-embedding, ivy-4-embedding-mm | 임베딩 생성 | LLM_FREE |
| Ivy | ivy-4-mm | 대화형 추론 | LLM_FREE |
| Cova | cova-1 | LLM 기반 비전 OCR. 텍스트·레이아웃·표 추출과 간단한 이미지 설명 |
계정에서 실제로 호출되는 모델은 플레이그라운드의 모델 목록과 GET /models 응답이 기준입니다. 플랜 표는 플랜이 여는 범위이며, 그 밖의 경로로 열린 모델은 담지 않습니다. 플랜 표의 cip-5.5-im-chat, cip-5.5-mm-h, cosa-tts는 제품군 문서에 설명이 없는 ID이고, cip-5.5-sm과 cova-1은 플랜 표에 없습니다.
제품군을 연결하면 다음 흐름을 구성할 수 있습니다.
- 문서 기반 업무: Cova가 본문·표·이미지 설명을 추출하고, CIP가 필요한 원본을 선택적으로 확인해 분석과 업무 처리를 수행하며, Cosa가 결과를 음성으로 전달합니다.
- 음성 기반 업무: cosa-asr이 음성 요청을 텍스트로 변환하고, CIP가 처리한 답변을 cosa-a 또는 cosa-b가 읽어 줍니다.
- 현장 자동화: cip-5.5-sm이 현장 데이터를 분류하고 로컬 업무를 수행하며, 추가 종합 분석이 필요한 자료를 cip-5.5-im 또는 cip-5.5-mm으로 넘깁니다.
호출 경로와 인증
두 호환 규격은 같은 API 키를 쓰고, 대화형 추론 모델은 어느 규격으로도 부를 수 있습니다. 임베딩과 음성·보이스 경로는 OpenAI 호환 규격에만 있습니다.
| 항목 | 값 |
|---|---|
| OpenAI 호환 base URL | https://platform.clevi.net/api/v2/aiservice/openai/v1 |
| Anthropic 호환 base URL | https://platform.clevi.net/api/v2/aiservice/anthropic (SDK가 /v1을 스스로 붙임) |
| 인증 헤더 | X-API-Key: <키> 또는 Authorization: Bearer <키>. 둘 다 지정하면 X-API-Key 값이 우선 적용됨 |
| OpenAI 호환 규격의 경로 | chat/completions, responses, completions, embeddings, models, audio, voices |
| Anthropic 호환 규격의 경로 | v1/messages, v1/messages/count_tokens, v1/models |
| 스트리밍 | 요청 본문에 stream: true를 넣으면 Server-Sent Events로 응답. embeddings는 스트리밍 없음 |
| 키 발급 화면 | 콘솔의 API 키 화면 |
| 한도와 사용량 | 워크스페이스마다 다르며 콘솔의 개요, 플랜과 크레딧, 사용량 화면에서 확인 |
오류는 HTTP 상태 코드로 알립니다. 업스트림이 4xx·5xx를 반환하면 그 코드를 그대로 전달하고, 402는 반환하지 않습니다. 헤더 규칙은 API 키로 인증하기 문서에, 경로별 동작은 API 호출하기 문서에, 코드별 대처는 오류 코드 문서에 있습니다.
콘솔 화면
| 화면 | 하는 일 |
|---|---|
| 시작 가이드 | 키 발급부터 첫 호출까지 3단계로 안내합니다. |
| API 키 | 키 발급과 폐기, 사용 범위를 관리합니다. |
| 플레이그라운드 | 호출 가능한 모델 목록을 보고 브라우저에서 바로 호출합니다. |
| 사용량 | 모델별·키별 호출량과 예상 차감 크레딧을 확인합니다. |
| 개요 | 워크스페이스에 걸린 할당된 사용 한도를 확인합니다. |
| 플랜과 크레딧 | 플랜이 허용하는 범위와 잔액을 확인합니다. |
| 도움말과 문의 | 5xx가 반복될 때 X-Request-Id와 함께 문의합니다. |
관련 문서
- 빠른 시작: 키 발급부터 첫 chat/completions 호출과 스트리밍까지
- 모델: 전체 모델 목록, 사양, 허용된 호출
- API 키로 인증하기: 인증 헤더, base URL, 선택 헤더
- API 호출하기: 규격별 경로, 스트리밍 규칙, 음성·보이스 규칙
- 오류 코드: 상태 코드별 대처, 재시도, 오류 본문