API 호출하기

CLEVI 게이트웨이의 호출 경로는 OpenAI 호환 규격과 Anthropic 호환 규격으로 나뉩니다.
두 규격은 같은 API 키를 사용하며, 대화형 추론 모델은 어느 규격으로도 호출할 수 있습니다.
임베딩과 음성·보이스 경로는 OpenAI 호환 규격에만 있고,
Anthropic 호환 규격은 messages, count_tokens, models 세 경로를 제공합니다.

스트리밍은 요청 본문의 stream으로 켜며, 임베딩과 일부 모델·경로는 지원하지 않습니다. 음성·보이스 경로는 오디오를 그대로 반환하고 산출물을 CleviDrive에 3일 동안 보관하는 등 일반 추론과 다른 규칙을 따릅니다.

모델 ID와 모델별 허용 호출은 모델 페이지에, 인증 헤더와 base URL은 API 키로 인증하기 페이지에 있습니다.

경로 선택

하려는 일과 사용 중인 SDK에 따라 경로를 선택하세요. 표의 경로는 각 규격의 base URL 뒤에 이어지는 상대 경로입니다.

OpenAI 호환 경로

OpenAI 호환 규격의 base URL은 https://platform.clevi.net/api/v2/aiservice/openai/v1 입니다. 요청과 응답 본문은 OpenAI 규격을 따릅니다. 아래 표는 추론과 모델 경로를 호스트 기준 전체 경로로 표기하며, 음성·보이스 경로는 뒤의 음성과 보이스 경로 절에 정리했습니다.

chat/completions를 호출하는 최소 예제입니다. sk-... 자리에는 API 키 화면에서 발급한 키를, model에는 모델 페이지의 ID를 넣으세요.

curl https://platform.clevi.net/api/v2/aiservice/openai/v1/chat/completions \
  -H "X-API-Key: sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cip-5.5-im",
    "messages": [{"role": "user", "content": "안녕하세요"}]
  }'

그 밖의 경로

다음 경로는 진단, 레거시 호환, 중계 용도입니다.

요청과 응답 필드 전체는 OpenAPI 3.0 문서 https://platform.clevi.net/api/v2/console/openapi/cloud-inference-v1 에서 확인할 수 있습니다. 경로 목록은 이 문서에서 생성되며, 문서는 콘솔에 로그인한 세션으로만 열립니다. 같은 문서로 클라이언트를 생성할 수 있습니다.

Anthropic 호환 경로

Anthropic 호환 규격의 base URL은 https://platform.clevi.net/api/v2/aiservice/anthropic 이며, Anthropic SDK가 요청 경로에 /v1을 직접 추가합니다. 요청과 응답 본문은 Anthropic Messages 규격을 따릅니다.

messages를 호출하는 최소 예제입니다.

curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/messages \
  -H "X-API-Key: sk-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cip-5.5-im",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "안녕하세요"}]
  }'

anthropic-version 헤더를 생략하면 2023-06-01로 처리합니다. 게이트웨이는 anthropic-version과 anthropic-beta 헤더를 그대로 전달합니다.

스트리밍 (SSE)

요청 본문에 stream을 true로 설정하면 서버가 Server-Sent Events로 응답합니다. 지원 여부는 경로와 모델에 따라 다음과 같이 다릅니다.

첫 청크와 함께 다음 세 헤더를 보냅니다. 이후에는 청크마다 data: 줄을 보내고 즉시 flush하며, 업스트림이 이벤트 이름을 제공한 경우에만 event: 줄을 함께 보냅니다.

• Content-Type: text/event-stream
• Cache-Control: no-cache
• X-Accel-Buffering: no

Anthropic 호환 경로의 청크는 event 줄과 data 줄이 짝을 이룹니다.

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"안"}}

chat/completions의 청크는 data 줄로 오며, 마지막에 data: [DONE]을 그대로 전달합니다.

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[...]}

data: [DONE]

스트리밍 도중 오류가 발생하면 일반 호출과 같은 오류 JSON이 data: 한 줄로 전달되고, HTTP 상태 코드도 함께 바뀝니다.

음성과 보이스 경로

TTS·STT와 Cosa 보이스 관리 경로는 OpenAI 호환 규격에 있으며, 일반 추론과 다른 규칙이 몇 가지 적용됩니다. 어떤 모델이 어느 경로를 허용하는지는 모델 페이지의 Cosa 표에서 확인하세요.

다음 규칙은 음성·보이스 경로에만 적용됩니다.