# Chat Completions > OpenAI Chat Completions 형식의 API입니다. POST /v1/chat/completions로 호출합니다. SDK는 `pip install openai` 또는 `npm install openai` 명령으로 설치합니다. 시스템 프롬프트는 `messages` 배열의 첫 번째 항목에 `role: "system"`으로 지정하며, 모델의 역할과 말투, 응답 규칙을 정의할 때 사용합니다. ```bash tab="curl" curl https://raon-api.krafton.ai/v1/chat/completions \ -H "Authorization: Bearer $RAON_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "raon-1-mini-preview", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ] }' ``` ```python tab="Python" import os from openai import OpenAI client = OpenAI( base_url="https://raon-api.krafton.ai/v1", api_key=os.environ["RAON_API_KEY"], ) completion = client.chat.completions.create( model="raon-1-mini-preview", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"}, ], ) print(completion.choices[0].message.content) ``` ```ts tab="TypeScript" import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://raon-api.krafton.ai/v1", apiKey: process.env.RAON_API_KEY, }); const completion = await client.chat.completions.create({ model: "raon-1-mini-preview", messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: "Hello!" }, ], }); console.log(completion.choices[0].message.content); ``` 생성된 답변은 `message.content`에, 모델의 추론 내용은 `message.reasoning`에 별도로 반환됩니다. `finish_reason`은 생성이 종료된 사유를 나타내며, 값은 다음과 같습니다. | 값 | 설명 | | --- | --- | | `stop` | 답변 생성 완료 | | `tool_calls` | 모델의 [도구](/ko/docs/tool-calling) 호출 요청 | | `length` | `max_tokens` 도달 | 추론 토큰도 `max_tokens`에 포함되므로, 값이 너무 작으면 답변이 비어 있을 수 있습니다. 자세한 내용은 [추론](/ko/docs/reasoning#추론과-max_tokens)을 참고하세요. ## 멀티턴 대화 [#멀티턴-대화] Raon은 대화 내용을 서버에 저장하지 않습니다. 요청할 때마다 이전 대화 전체를 `messages`에 포함하고, 모델의 답변은 `assistant` 메시지로 추가하세요. 추론 내용은 대화 기록에 포함하지 않아도 됩니다. ## 관련 문서 [#관련-문서] - 이 API에서 사용할 수 있는 기능: [스트리밍](/ko/docs/streaming), [구조화된 출력](/ko/docs/structured-outputs), [웹 검색](/ko/docs/web-search), [도구 호출](/ko/docs/tool-calling) - 전체 파라미터: [API 레퍼런스](/ko/docs/api-reference) --- # Claude Code > 별도 명령으로 Claude Code를 Raon에 연결합니다. 기존 Claude 설정은 변경하지 않습니다. 설치 스크립트는 Raon 모델로 Claude Code를 실행하는 `raon-claude` 명령을 추가합니다. 기존 `claude` 명령과 `~/.claude/settings.json`은 변경하지 않으므로, 기존 계정도 그대로 사용할 수 있습니다. ## 설치 [#설치] ```bash tab="macOS / Linux" curl -fsSL https://raon-console.krafton.ai/setup/claude-code.sh | bash ``` ```powershell tab="Windows (PowerShell)" irm https://raon-console.krafton.ai/setup/claude-code.ps1 | iex ``` 설치 스크립트는 Claude Code가 설치되어 있지 않으면 먼저 설치합니다. 이어서 API 키를 입력받아 테스트 호출을 수행한 후, 다음 파일을 생성합니다. | 파일 | 내용 | | --- | --- | | `~/.raon/claude-code.json` | Raon 설정 (본인만 읽기 가능) | | `~/.local/bin/raon-claude` | `claude --settings ~/.raon/claude-code.json`을 실행하는 명령 | 이전 버전의 설치 스크립트가 `~/.claude/settings.json`을 변경했다면, 다시 실행할 때 원래 값으로 복원합니다. ## 실행 [#실행] ```bash raon-claude raon-claude -p "Explain this repository" ``` ## 수동 설정 [#수동-설정] 다음 내용을 `~/.raon/claude-code.json`으로 저장하고, 본인만 읽을 수 있도록 파일 권한을 설정하세요. ```json title="~/.raon/claude-code.json" { "env": { "ANTHROPIC_BASE_URL": "https://raon-api.krafton.ai", "ANTHROPIC_AUTH_TOKEN": "", "ANTHROPIC_MODEL": "raon-1-mini-preview", "ANTHROPIC_DEFAULT_OPUS_MODEL": "raon-1-mini-preview", "ANTHROPIC_DEFAULT_SONNET_MODEL": "raon-1-mini-preview", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "raon-1-mini-preview", "CLAUDE_CODE_SUBAGENT_MODEL": "raon-1-mini-preview" } } ``` 이 파일을 지정해 Claude Code를 실행합니다. 지정한 설정은 해당 세션에서만 `~/.claude/settings.json`보다 우선 적용됩니다. ```bash claude --settings ~/.raon/claude-code.json ``` - `ANTHROPIC_BASE_URL`에는 `/v1`을 붙이지 않습니다. Claude Code가 자동으로 추가합니다. - 모든 모델 별칭을 Raon 모델로 지정해야 백그라운드 호출과 서브에이전트도 Raon 모델을 사용합니다. - 특정 도구 호출을 강제하는(`tool_choice.type: "tool"`) Claude Code WebSearch 요청은 지원하지 않으며, 400 오류가 반환됩니다. ## 제거 [#제거] Raon 전용 설정과 로컬에 저장된 API 키, 실행 스크립트를 제거합니다. Claude Code 프로그램은 삭제하지 않으며, 서버에서 발급한 API 키도 폐기하지 않습니다. 에이전트별 제거 범위는 [설치 옵션](/ko/docs/installer-options#설치-제거)을 참고하세요. ```bash tab="macOS / Linux" curl -fsSL https://raon-console.krafton.ai/setup/claude-code.sh | bash -s -- --uninstall ``` ```powershell tab="Windows (PowerShell)" & ([scriptblock]::Create((irm https://raon-console.krafton.ai/setup/claude-code.ps1))) -Uninstall ``` --- # Codex > 별도 프로필과 명령으로 Codex를 Raon에 연결합니다. 기존 Codex 설정은 변경하지 않습니다. 설치 스크립트는 Codex의 `raon` 프로필과, Raon 모델로 Codex를 실행하는 `raon-codex` 명령을 추가합니다. 기존 `codex` 명령과 `~/.codex/config.toml`은 변경하지 않습니다. ## 설치 [#설치] ```bash tab="macOS / Linux" curl -fsSL https://raon-console.krafton.ai/setup/codex.sh | bash ``` ```powershell tab="Windows (PowerShell)" irm https://raon-console.krafton.ai/setup/codex.ps1 | iex ``` 설치 스크립트를 사용하려면 Codex 0.134.0 이상이 필요합니다. Codex가 없거나 버전이 낮으면 설치 또는 업데이트를 안내합니다. 이어서 API 키를 입력받아 테스트 호출을 수행한 후, 다음 파일을 생성합니다. | 파일 | 내용 | | --- | --- | | `~/.codex/raon.config.toml` | `raon` 프로필 (전용 모델 프로바이더 포함) | | `~/.codex/raon.key` | API 키 (본인만 읽기 가능) | | `~/.local/bin/raon-codex` | `codex --profile raon`을 실행하는 명령 | `CODEX_HOME`이 설정되어 있으면 `~/.codex` 대신 해당 경로를 사용합니다. 이전 버전의 설치 스크립트가 `config.toml`을 변경했다면, 다시 실행할 때 원래 값으로 복원합니다. ## 실행 [#실행] ```bash raon-codex raon-codex exec "Explain this repository" codex --profile raon # 명령 없이 같은 동작 ``` 웹 검색은 Codex 기본 설정으로 사용할 수 있습니다. 조직 정책상 웹 검색을 사용하지 않는다면 `web_search = "disabled"`로 설정하세요. `apply_patch`를 freeform 커스텀 도구로 활성화하지 마세요. Raon 백엔드가 해당 도구 호출 기록을 처리하지 못합니다. ## 수동 설정 [#수동-설정] 다음 내용을 `~/.codex/raon.config.toml`로 저장하고, API 키는 `RAON_API_KEY` 환경 변수에 설정하세요. 이 파일은 `codex --profile raon`으로 실행할 때만 적용되며, 기존 `codex` 명령에는 영향을 주지 않습니다. ```toml title="~/.codex/raon.config.toml" model = "raon-1-mini-preview" model_provider = "raon" model_context_window = 262144 [model_providers.raon] name = "Raon" base_url = "https://raon-api.krafton.ai/v1" wire_api = "responses" env_key = "RAON_API_KEY" ``` `model_context_window`는 모델의 컨텍스트 윈도우인 262144 이하로 설정하세요. ## 제거 [#제거] Raon 전용 설정과 로컬에 저장된 API 키, 실행 스크립트를 제거합니다. Codex 프로그램은 삭제하지 않으며, 서버에서 발급한 API 키도 폐기하지 않습니다. 에이전트별 제거 범위는 [설치 옵션](/ko/docs/installer-options#설치-제거)을 참고하세요. ```bash tab="macOS / Linux" curl -fsSL https://raon-console.krafton.ai/setup/codex.sh | bash -s -- --uninstall ``` ```powershell tab="Windows (PowerShell)" & ([scriptblock]::Create((irm https://raon-console.krafton.ai/setup/codex.ps1))) -Uninstall ``` --- # 기타 호환 도구 > OpenAI 호환 커스텀 프로바이더를 지원하는 도구를 Raon에 연결합니다. opencode, pi, Cline, Continue 등 대부분의 코딩 에이전트와 채팅 앱은 OpenAI 호환 커스텀 프로바이더를 추가할 수 있습니다. 도구의 프로바이더 설정에 다음 값을 입력하세요. | 설정 | 값 | | --- | --- | | API 유형 | OpenAI 호환, Chat Completions | | Base URL | `https://raon-api.krafton.ai/v1` | | API 키 | 발급받은 API 키 (도구가 지원하면 `RAON_API_KEY` 환경 변수에서 읽도록 설정) | | 모델 ID | `raon-1-mini-preview` | | 컨텍스트 윈도우 | 262144 | | 최대 출력 토큰 수 | 16384 권장 (추론 토큰 포함) | | 추론 | 항상 활성화. 클라이언트 설정은 무시. 추론 내용은 `message.reasoning`으로 반환 | | 입력 형식 | 텍스트만 지원 | ## 예시: opencode [#예시-opencode] 프로젝트 폴더 또는 `~/.config/opencode/`의 `opencode.json`에 프로바이더를 추가합니다. ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "provider": { "raon": { "npm": "@ai-sdk/openai-compatible", "name": "Raon", "options": { "baseURL": "https://raon-api.krafton.ai/v1", "apiKey": "{env:RAON_API_KEY}" }, "models": { "raon-1-mini-preview": { "name": "Raon-1 mini preview", "limit": { "context": 262144, "output": 16384 } } } } }, "model": "raon/raon-1-mini-preview" } ``` `model`을 지정하면 Raon이 기본 모델로 설정됩니다. 지정하지 않으면 opencode에서 `/models` 명령으로 모델을 선택하세요. ## 문제가 발생하는 경우 [#문제가-발생하는-경우] - 모든 요청이 404를 반환하면 Base URL의 `/v1`이 빠졌거나 중복되었는지 확인하세요. - 답변이 비어 있으면 최대 출력 토큰 수가 추론에 비해 작은 경우가 많습니다. 값을 늘리세요. - Anthropic 형식만 지원하는 도구는 Base URL을 `/v1` 없이 `https://raon-api.krafton.ai`로 지정합니다. 자세한 내용은 [Messages](/ko/docs/messages)를 참고하세요. --- # 오류 > 오류 응답 형식, 상태 코드, 재시도 기준, 타임아웃입니다. ## 오류 형식 [#오류-형식] Raon 게이트웨이는 직접 생성한 오류를 API별 응답 형식에 맞춰 반환합니다. Chat Completions, Responses, `GET /v1/models`의 오류 응답 형식은 다음과 같습니다. ```json { "error": { "message": "Incorrect API key provided.", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } ``` Messages에서는 게이트웨이가 생성한 오류를 다음과 같은 Anthropic 형식으로 반환합니다. 이 형식에는 `code` 필드가 없습니다. ```json { "type": "error", "error": { "type": "authentication_error", "message": "Incorrect API key provided." } } ``` SDK는 오류 응답을 `openai.AuthenticationError`, `anthropic.RateLimitError` 같은 예외로 변환합니다. 모델 서버에서 발생한 입력 검증 오류는 다른 형식으로 전달될 수 있습니다. 예를 들어 Messages 요청에 대한 HTTP 400 응답에도 최상위 `type` 필드 없이 `error.type: "upstream_error"`와 `error.code: "upstream_http_error"`가 포함될 수 있습니다. 예기치 않은 내부 오류도 OpenAI 형식으로 반환될 수 있습니다. Messages의 오류 응답을 처리할 때는 위 예시 외의 형식도 고려해 HTTP 상태 코드와 전체 응답 본문을 확인하세요. ## 상태 코드 [#상태-코드] | 상태 코드 | `code` | 원인 | 재시도 여부 | | --- | --- | --- | --- | | 400 | `invalid_request` | 잘못된 JSON 본문, 필수 필드 누락, [지원하지 않는 기능](/ko/docs/limits) 사용 | 아니요 (요청 수정) | | 400 | `unsupported_tool` | Raon이 실행하지 않는 도구 사용 (예: `code_interpreter`) | 아니요 | | 400 | `token_limit_exceeded` | 단일 요청의 분당 토큰 한도 초과 | 아니요 | | 400 | — | 입력과 `max_tokens`의 합이 컨텍스트 윈도우 초과 | 아니요 (입력 축소) | | 401 | `invalid_api_key` | API 키 누락, 오류, 비활성화 또는 만료 | 아니요 | | 402 | `insufficient_credit`, `spend_limit_exceeded` | 크레딧 부족 또는 월 지출 한도 도달 | 아니요 | | 403 | `model_not_allowed` | 잘못된 모델 ID 또는 API 키로 사용할 수 없는 모델 | 아니요 | | 404 | — | 제공하지 않는 경로 (주로 Base URL의 `/v1` 누락 또는 중복) | 아니요 | | 413 | `payload_too_large` | 요청 본문 크기 28 MiB 초과 | 아니요 | | 429 | `rate_limit_exceeded`, `overloaded` | [속도 제한](/ko/docs/rate-limits) 초과 또는 서비스 과부하 | 예 (`retry-after` 이후) | | 500 | — | Raon 내부 오류 | 예 (지수 백오프) | | 502 | `upstream_error` | 모델 서버 오류 또는 응답 시간 초과 | 예 (지수 백오프) | 재시도할 때는 지수 백오프로 대기 시간을 점차 늘리고, 재시도 횟수에 상한을 두세요. 429를 제외한 4xx 오류는 같은 요청을 다시 보내도 같은 이유로 실패하므로 재시도하지 마세요. 이번 프리뷰의 모델 이용 요금은 0원입니다. 다만 조직의 크레딧이나 지출 한도 정책에 따라 HTTP 402 오류가 발생할 수 있습니다. 이 경우 프리뷰 운영자에게 문의하세요. ## 스트리밍 중 오류 [#스트리밍-중-오류] 스트리밍 응답은 시작 시점에 이미 상태 코드 200을 반환하므로, 이후 발생한 오류는 스트림 안의 이벤트로 전달됩니다. | API | 오류 이벤트 | | --- | --- | | Chat Completions | `{"error": {...}}`를 포함한 `data:` 행 | | Responses | `event: error` | | Messages | Anthropic 형식의 `event: error` | SDK는 스트림을 읽는 중에 이 이벤트를 받으면 예외를 발생시킵니다. 오류 이전에 받은 텍스트는 완전한 답변이 아니므로, 전체 답변이 필요하면 요청을 다시 보내세요. ## 타임아웃 [#타임아웃] 추론이나 웹 검색이 포함되면 응답까지 몇 분이 걸릴 수 있습니다. Raon은 요청당 최대 10분까지 처리하므로, 클라이언트 타임아웃도 10분 이상으로 설정하세요. OpenAI SDK와 Anthropic SDK의 기본 타임아웃은 10분입니다. - 스트리밍을 사용하면 진행 상황을 바로 확인할 수 있고 연결도 유지됩니다. 웹 검색 중처럼 10초 동안 전송할 데이터가 없으면 Raon이 `: ping` 주석 행을 보냅니다. SSE 클라이언트는 이 행을 무시합니다. - 클라이언트 연결이 끊기면 Raon도 요청 처리를 중단합니다. - 요청에는 `Content-Length` 헤더가 필요합니다. SDK와 curl은 이 헤더를 자동으로 추가합니다. 이 헤더 없이 chunked 방식으로 전송하면 411 오류가 반환됩니다. ## 문의 시 필요한 정보 [#문의-시-필요한-정보] 문제를 문의할 때는 요청 시각, 응답 헤더의 `x-request-id`, 상태 코드, 오류 응답 본문을 함께 전달해 주세요. `x-request-id`는 Raon이 생성하는 요청 추적용 UUID이며 스트리밍 응답에도 포함됩니다. 요청에 같은 이름의 헤더를 보내도 해당 값은 사용하지 않습니다. --- # 문제 해결 > 자주 겪는 문제와 해결 방법입니다. ## 답변이 비어 있는 경우 [#답변이-비어-있는-경우] `content`가 비어 있거나 `null`이고 `finish_reason`이 `length`라면(Messages는 `stop_reason: "max_tokens"`, Responses는 `status: "incomplete"`), 모델이 답변을 생성하기 전에 추론에 `max_tokens`를 모두 사용한 것입니다. [추론](/ko/docs/reasoning)과 답변을 모두 생성할 수 있도록 `max_tokens`를 늘리세요. 어려운 질문은 추론에만 수천 토큰이 사용될 수 있습니다. ## 모든 요청이 404를 반환하는 경우 [#모든-요청이-404를-반환하는-경우] Base URL의 `/v1` 포함 여부를 확인하세요. OpenAI SDK와 대부분의 OpenAI 호환 도구는 `https://raon-api.krafton.ai/v1`을 사용합니다. Anthropic SDK와 Claude Code는 `/v1`을 자동으로 추가하므로 `https://raon-api.krafton.ai`를 사용합니다. ## 403 `model_not_allowed` 오류가 발생하는 경우 [#403-model_not_allowed-오류가-발생하는-경우] API 키로 사용할 수 없는 모델 ID를 지정한 경우입니다. 다른 서비스의 모델 이름 대신 `raon-1-mini-preview`를 사용하세요. 사용할 수 있는 모델 ID는 `GET /v1/models`로 확인할 수 있습니다. ## 401 `invalid_api_key` 오류가 발생하는 경우 [#401-invalid_api_key-오류가-발생하는-경우] 요청에 API 키가 포함되어 있는지, 콘솔의 API 키 화면에서 해당 키가 삭제되거나 만료되지 않았는지 확인하세요. Chat Completions와 Responses는 `Authorization: Bearer ` 헤더를 사용하며, Messages는 `x-api-key` 헤더도 사용할 수 있습니다. ## 응답이 느리거나 타임아웃이 발생하는 경우 [#응답이-느리거나-타임아웃이-발생하는-경우] 추론과 웹 검색이 포함되면 응답에 몇 분이 걸릴 수 있습니다. 다음 사항을 확인하세요. - 스트리밍으로 진행 상황을 확인합니다. - 클라이언트 타임아웃을 10분 이상으로 설정합니다. - 추론과 답변에 필요한 출력 토큰 수를 충분히 지정합니다. 자세한 내용은 [타임아웃](/ko/docs/errors#타임아웃)을 참고하세요. ## 429 오류가 발생하는 경우 [#429-오류가-발생하는-경우] `retry-after`에 지정된 시간만큼 기다린 후 재시도하고, 동시 요청 수를 줄이세요. 자세한 내용은 [속도 제한](/ko/docs/rate-limits)을 참고하세요. ## 이미지나 파일 내용을 인식하지 못하는 경우 [#이미지나-파일-내용을-인식하지-못하는-경우] 모델은 텍스트 입력만 지원합니다. 문서는 텍스트로 변환해 메시지에 포함하세요. 이미지와 오디오는 지원하지 않습니다. ## 이전 대화 내용을 기억하지 못하는 경우 [#이전-대화-내용을-기억하지-못하는-경우] Raon은 대화 내용을 서버에 저장하지 않습니다. 요청할 때마다 이전 메시지와 모델의 이전 답변을 함께 보내세요. 일반 텍스트 대화에서는 이전 응답의 추론 내용을 생략할 수 있습니다. Responses API의 출력 항목을 다음 요청에 다시 보낼 때는 `reasoning` 항목과 관련 출력 항목의 순서를 유지하세요. 자세한 내용은 [API 레퍼런스](/ko/docs/api-reference)를 참고하세요. ## 코딩 에이전트가 실행되지 않거나 다른 모델을 사용하는 경우 [#코딩-에이전트가-실행되지-않거나-다른-모델을-사용하는-경우] 에이전트 설치 스크립트를 다시 실행하세요. 설치 스크립트가 API 키를 테스트하고 설정을 다시 작성합니다. 수동 설정 방법은 각 에이전트 문서를 참고하세요. Claude Code와 Codex는 `raon-claude`, `raon-codex` 명령으로 실행해야 합니다. `claude`, `codex` 명령은 기존 설정을 그대로 사용합니다. --- # Hermes > Raon을 Hermes 프로바이더로 등록하고 기본 모델로 설정할지 선택합니다. 설치 스크립트는 Raon을 Hermes 프로바이더 `custom:raon`으로 등록하고, 기본 모델로 설정할지 묻습니다. 동의하면 기본 모델을 Raon으로 변경하고, 거절하면 기존 기본 모델을 유지합니다. 다른 프로바이더 설정은 변경하지 않으며, `hermes model` 명령으로 다른 프로바이더로 전환할 수 있습니다. 기본 모델을 변경할지 묻는 단계에서 Enter 키를 누르면 Raon으로 변경합니다. `--yes` 옵션(Windows는 `-Yes`)을 지정해도 기본 모델을 Raon으로 변경합니다. 사용자 입력을 받을 수 없는 환경에서 이 옵션 없이 실행하면 Raon만 등록하고 기존 기본 모델을 유지합니다. ## 설치 [#설치] ```bash tab="macOS / Linux" curl -fsSL https://raon-console.krafton.ai/setup/hermes.sh | bash ``` ```powershell tab="Windows (PowerShell)" irm https://raon-console.krafton.ai/setup/hermes.ps1 | iex ``` 설치 스크립트는 Hermes가 설치되어 있지 않으면 먼저 설치한 후, API 키를 입력받아 테스트 호출을 수행합니다. Hermes는 본인만 읽을 수 있는 `~/.raon/hermes.key` 파일에서 API 키를 읽습니다. ## 실행 [#실행] ```bash hermes hermes -z "Explain this repository" hermes model # 프로바이더 전환 ``` ## 수동 설정 [#수동-설정] Hermes의 `.env` 파일(`~/.hermes/.env`, Windows는 `%LOCALAPPDATA%\hermes\.env`)에 API 키를 추가하고 프로바이더를 등록합니다. ```bash echo 'RAON_API_KEY=' >> ~/.hermes/.env hermes config set providers.raon '{"name":"Raon","api":"https://raon-api.krafton.ai/v1","key_env":"RAON_API_KEY","transport":"chat_completions","default_model":"raon-1-mini-preview","models":{"raon-1-mini-preview":{"context_length":262144}}}' hermes config set model.provider custom:raon hermes config set model.default raon-1-mini-preview hermes config set model.base_url https://raon-api.krafton.ai/v1 ``` ## 제거 [#제거] 설치 스크립트가 등록한 Raon 프로바이더와 저장한 API 키를 제거합니다. Hermes 프로그램과 다른 프로바이더의 설정, 도구 설정은 유지합니다. 설치 스크립트가 기본 모델을 Raon으로 변경했다면 설치 전 기본 모델로 복원합니다. 설치 후 사용자가 기본 모델을 변경한 경우에는 사용자가 지정한 값을 유지합니다. ```bash tab="macOS / Linux" curl -fsSL https://raon-console.krafton.ai/setup/hermes.sh | bash -s -- --uninstall ``` ```powershell tab="Windows (PowerShell)" & ([scriptblock]::Create((irm https://raon-console.krafton.ai/setup/hermes.ps1))) -Uninstall ``` 설치 전에 같은 이름의 Raon 프로바이더나 API 키가 있었다면 원래 값으로 복원합니다. 다만 Raon 프로바이더를 수정했거나 기본 설정 복원 후에도 기본 프로바이더가 Raon으로 설정되어 있으면 프로바이더와 키를 유지하고 그 이유를 표시합니다. 설치할 때는 Raon을 등록만 하고 나중에 기본 모델로 선택한 경우에도 프로바이더와 키를 유지합니다. 설치 후 변경한 API 키도 삭제하지 않습니다. 제거할 때는 설치 스크립트가 남긴 기록을 참조합니다. 수동으로 추가한 설정이나 설치 기록이 없는 이전 버전의 설정은 자동으로 제거하지 않습니다. API 키를 입력하거나 API 서버에 연결할 필요는 없습니다. 다만 설정 변경에 에이전트의 명령을 사용하므로 Hermes가 설치되어 있어야 합니다. 로컬에 저장한 키를 삭제해도 서버에서 발급한 API 키는 폐기되지 않습니다. --- # 시작하기 > API 키를 발급받고 Raon에 첫 요청을 보냅니다. Raon은 `raon-1-mini-preview` 모델을 널리 사용되는 세 가지 API 형식으로 제공합니다. OpenAI·Anthropic SDK나 Raon과 호환되는 코딩 에이전트에서 Base URL, API 키, 모델 ID를 설정해 텍스트 생성 기능을 사용할 수 있습니다. 다른 API 서비스를 사용하던 코드를 Raon에 연결할 때는 [지원 기능과 제한](/ko/docs/limits)을 확인하세요. 이번 프리뷰의 모델 이용 요금은 0원입니다. 토큰 사용량은 계속 집계하며, 속도 제한도 적용합니다. ## Base URL [#base-url] 모든 API 요청은 다음 주소로 보냅니다. ```txt title="Base URL" https://raon-api.krafton.ai ``` ## API 키 발급 [#api-키-발급] 콘솔의 [API 키](https://raon-console.krafton.ai/api-keys) 화면에서 API 키를 발급합니다. API 키는 코드에 직접 작성하지 말고 환경 변수로 관리하세요. ```bash tab="macOS / Linux" export RAON_API_KEY="" ``` ```powershell tab="Windows (PowerShell)" $env:RAON_API_KEY = "" ``` API 키는 `Authorization: Bearer ` 헤더에 담아 보냅니다. Messages API는 Anthropic SDK가 사용하는 `x-api-key` 헤더도 지원합니다. ## 첫 요청 보내기 [#첫-요청-보내기] ```bash tab="curl" curl https://raon-api.krafton.ai/v1/chat/completions \ -H "Authorization: Bearer $RAON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "raon-1-mini-preview", "messages": [{"role": "user", "content": "Hello!"}]}' ``` ```python tab="Python" import os from openai import OpenAI client = OpenAI( base_url="https://raon-api.krafton.ai/v1", api_key=os.environ["RAON_API_KEY"], ) completion = client.chat.completions.create( model="raon-1-mini-preview", messages=[{"role": "user", "content": "Hello!"}], ) print(completion.choices[0].message.content) ``` ```ts tab="TypeScript" import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://raon-api.krafton.ai/v1", apiKey: process.env.RAON_API_KEY, }); const completion = await client.chat.completions.create({ model: "raon-1-mini-preview", messages: [{ role: "user", content: "Hello!" }], }); console.log(completion.choices[0].message.content); ``` curl 예제는 macOS·Linux 셸 기준입니다. Windows에서는 WSL이나 Git Bash에서 실행하거나 Python, TypeScript 예제를 사용하세요. ## API 형식 [#api-형식] 사용하는 클라이언트와 같은 형식의 API를 호출하세요. API 간 요청 형식은 변환되지 않습니다. 클라이언트별 연결 방법은 [SDK와 프레임워크](/ko/docs/sdks)를 참고하세요. | 엔드포인트 | API 형식 | 사용 클라이언트 | | --- | --- | --- | | [`POST /v1/chat/completions`](/ko/docs/chat-completions) | OpenAI Chat Completions | OpenClaw, Hermes, [기타 호환 도구](/ko/docs/compatible-tools) | | [`POST /v1/responses`](/ko/docs/responses) | OpenAI Responses | Codex | | [`POST /v1/messages`](/ko/docs/messages) | Anthropic Messages | Claude Code | `GET /v1/models`는 API 키로 사용할 수 있는 모델 목록을 컨텍스트 윈도우, 요금 정보와 함께 반환합니다. ```bash curl https://raon-api.krafton.ai/v1/models \ -H "Authorization: Bearer $RAON_API_KEY" ``` ## AI 에이전트용 문서 [#ai-에이전트용-문서] 이 문서는 AI 에이전트가 읽을 수 있도록 [llms.txt](https://llmstxt.org) 형식으로도 제공됩니다. 코딩 에이전트에게 Raon 연동 작업을 맡길 때는 먼저 `llms.txt`를 읽도록 지시하세요. ```txt title="요청 예시" https://raon-mini.krafton.ai/ko/llms.txt 와 연결된 문서를 읽고, 이 앱에 Chat Completions API로 Raon을 연동해 줘. ``` | 주소 | 내용 | | --- | --- | | [`/ko/llms.txt`](/ko/llms.txt) | 전체 페이지의 Markdown 링크 목차 (영문: [`/llms.txt`](/llms.txt)) | | [`/ko/llms-full.txt`](/ko/llms-full.txt) | 전체 페이지를 하나로 합친 파일 | | [`/openapi.yaml`](/openapi.yaml) | OpenAPI 명세 (전체 엔드포인트, 파라미터, 거부 조건, 오류 형식) | 각 페이지 주소 끝에 `.md`를 붙이면 Markdown 문서를 볼 수 있습니다. 페이지 상단의 **Markdown 복사** 버튼으로 내용을 복사해 대화창에 붙여 넣을 수도 있습니다. ## 다음 단계 [#다음-단계] --- # 설치 옵션 > 사용자 입력 없이 설치 스크립트를 실행하는 방법과 Raon 연동을 제거하는 방법입니다. API 키는 `RAON_API_KEY` 환경 변수로도 전달할 수 있습니다. 입력 단계 없이 설치하려면 `bash -s --` 뒤에 옵션을 지정하세요. Windows에서는 스크립트를 스크립트 블록으로 실행합니다. ```bash tab="macOS / Linux" curl -fsSL https://raon-console.krafton.ai/setup/codex.sh | bash -s -- --yes --model raon-1-mini-preview ``` ```powershell tab="Windows (PowerShell)" & ([scriptblock]::Create((irm https://raon-console.krafton.ai/setup/codex.ps1))) -Yes -Model raon-1-mini-preview ``` | macOS / Linux | Windows (PowerShell) | 설명 | | --- | --- | --- | | `--api-key` | `-ApiKey` | API 키 | | `--model` | `-Model` | 모델 ID | | `--base-url` | `-BaseUrl` | API Base URL | | `--yes` | `-Yes` | 확인 없이 기본값으로 진행 | | `--uninstall` | `-Uninstall` | 설치 스크립트가 추가한 내용 제거 | | `--help` | `-Help` | 도움말 표시 | 스크립트를 셸로 바로 실행하기 전에 내용을 먼저 확인하세요. 스크립트 대신 각 에이전트 문서의 수동 설정 방법을 따를 수도 있습니다. ## 설치 제거 [#설치-제거] `--uninstall` 옵션은 Raon 연동을 위해 추가한 설정과 파일을 제거합니다. 이전 버전의 설치 스크립트가 `~/.claude/settings.json`이나 `~/.codex/config.toml`을 변경했다면, 해당 파일을 같은 디렉터리에 `.bak-<날짜>-<시각>`으로 백업한 뒤 원래 설정으로 복원합니다. 에이전트 프로그램은 삭제하지 않습니다. ```bash tab="macOS / Linux" curl -fsSL https://raon-console.krafton.ai/setup/claude-code.sh | bash -s -- --uninstall curl -fsSL https://raon-console.krafton.ai/setup/codex.sh | bash -s -- --uninstall curl -fsSL https://raon-console.krafton.ai/setup/hermes.sh | bash -s -- --uninstall curl -fsSL https://raon-console.krafton.ai/setup/openclaw.sh | bash -s -- --uninstall ``` ```powershell tab="Windows (PowerShell)" & ([scriptblock]::Create((irm https://raon-console.krafton.ai/setup/claude-code.ps1))) -Uninstall & ([scriptblock]::Create((irm https://raon-console.krafton.ai/setup/codex.ps1))) -Uninstall & ([scriptblock]::Create((irm https://raon-console.krafton.ai/setup/hermes.ps1))) -Uninstall & ([scriptblock]::Create((irm https://raon-console.krafton.ai/setup/openclaw.ps1))) -Uninstall ``` 네 에이전트 모두 같은 제거 옵션을 지원하며, 제거 범위는 다음과 같습니다. - Claude Code와 Codex: Raon 전용 설정, 로컬에 저장된 API 키, 실행 스크립트를 제거합니다. - OpenClaw와 Hermes: 설치 기록에 따라 Raon 프로바이더와 API 키를 제거하고, 설치 스크립트가 변경한 기본 모델을 복원합니다. 설치 전에 같은 이름의 설정이 있었다면 원래 값으로 복원합니다. 설치 후 사용자가 변경한 설정과 API 키는 유지합니다. Raon 프로바이더를 수정했거나 기본 설정 복원 후에도 전역 기본 모델이 Raon으로 설정되어 있으면 프로바이더와 키를 유지하고 그 이유를 표시합니다. 설치할 때는 Raon을 등록만 하고 나중에 기본 모델로 선택한 경우에도 프로바이더와 키를 유지합니다. OpenClaw의 개별 대화나 에이전트에 지정된 모델은 제거 시 확인하지 않습니다. 해당 모델도 다른 프로바이더의 모델로 변경한 뒤 Raon을 제거하세요. OpenClaw와 Hermes는 각각의 설정 디렉터리 안에 있는 `.raon-setup`에 설치 기록을 저장합니다. 수동으로 추가한 설정이나 설치 기록이 없는 이전 버전의 설정은 자동으로 제거하지 않습니다. 제거 시 API 서버에 연결할 필요는 없지만, 설정 변경에 각 에이전트의 명령을 사용하므로 해당 프로그램이 설치되어 있어야 합니다. 공용 `.raon` 디렉터리는 다른 에이전트의 파일이 남아 있으면 삭제하지 않습니다. 로컬에 저장한 키를 삭제해도 서버에서 발급한 API 키는 폐기되지 않습니다. OpenClaw와 Hermes 설치 시 `--yes` 옵션(Windows는 `-Yes`)을 지정하면 기본 모델도 Raon으로 변경합니다. 변경 전에 생성한 백업 파일은 보존합니다. --- # 지원하지 않는 요청 > Raon이 지원하지 않는 요청과 대체 방법입니다. Raon은 대화 상태를 서버에 저장하지 않으며, 서버에서 실행하는 도구는 웹 검색만 제공합니다. 따라서 다음 요청은 모델에 전달되지 않고 400 오류로 거부됩니다. 사용자 코드에서 실행하는 함수 도구는 제한 없이 사용할 수 있습니다. | API | 지원하지 않는 요청 | 대체 방법 또는 오류 코드 | | --- | --- | --- | | Responses | `previous_response_id`, `conversation`, `prompt`, `background: true`, `item_reference` 입력, `file_id`로 지정한 파일 | 전체 대화를 `input`에 포함 | | Responses | `file_search`, `code_interpreter`, computer use, 이미지 생성, `mcp` 도구 | `unsupported_tool` | | Messages | `web_fetch_*`, `code_execution_*`, `mcp_toolset` 도구와 `mcp_servers` | `unsupported_tool` | | Messages | `tool_choice`에서 특정 도구 지정(`type: "tool"`) | `tool_choice` 생략 또는 `auto`, `any`, `none` 사용 | | Messages | 업로드한 파일 참조(`source.type: "file"`), `container_upload`, `container` | 내용을 요청에 직접 포함 | | 공통 | 호출한 API를 지원하지 않는 모델 지정 | `model_not_supported_on_this_api` | 토큰 수 계산(`POST /v1/messages/count_tokens`), 저장된 응답 조회(`GET /v1/responses/{id}`) 등의 경로는 제공하지 않으며 404를 반환합니다. 지원하지 않는 요청은 API별 오류 형식으로 400 오류를 반환합니다. Chat Completions와 Responses에서는 `code` 필드에 `unsupported_tool` 같은 사유가 포함됩니다. 전체 상태 코드는 [오류](/ko/docs/errors)를 참고하세요. --- # Messages > Anthropic Messages 형식의 API입니다. POST /v1/messages로 호출합니다. SDK는 `pip install anthropic` 또는 `npm install @anthropic-ai/sdk` 명령으로 설치합니다. `max_tokens`는 필수 파라미터입니다. 시스템 프롬프트는 최상위 `system` 파라미터로 지정하며, `messages`에는 system 역할을 사용할 수 없습니다. ```bash tab="curl" curl https://raon-api.krafton.ai/v1/messages \ -H "x-api-key: $RAON_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "raon-1-mini-preview", "max_tokens": 1024, "system": "You are a helpful assistant.", "messages": [{"role": "user", "content": "Hello!"}] }' ``` ```python tab="Python" import os from anthropic import Anthropic client = Anthropic( base_url="https://raon-api.krafton.ai", # no /v1: the SDK adds it api_key=os.environ["RAON_API_KEY"], ) message = client.messages.create( model="raon-1-mini-preview", max_tokens=1024, system="You are a helpful assistant.", messages=[{"role": "user", "content": "Hello!"}], ) print(next(block.text for block in message.content if block.type == "text")) ``` ```ts tab="TypeScript" import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ baseURL: "https://raon-api.krafton.ai", // no /v1: the SDK adds it apiKey: process.env.RAON_API_KEY, }); const message = await client.messages.create({ model: "raon-1-mini-preview", max_tokens: 1024, system: "You are a helpful assistant.", messages: [{ role: "user", content: "Hello!" }], }); for (const block of message.content) { if (block.type === "text") console.log(block.text); } ``` 응답의 `content`에는 `thinking` 블록이 먼저 오고, 이어서 `text` 블록이 옵니다. `stop_reason`은 답변 생성이 완료되면 `end_turn`, `max_tokens`에 도달하면 `max_tokens`입니다. Anthropic SDK는 `/v1`을 자동으로 추가하므로 Base URL에 `/v1`을 포함하지 않습니다. Claude Code의 `ANTHROPIC_BASE_URL`도 마찬가지입니다. ## 도구 선택 [#도구-선택] `tool_choice`는 `auto`, `any`, `none`을 지원합니다. 특정 도구를 지정하면(`tool_choice.type: "tool"`) 400 오류가 반환되므로, `tool_choice`를 생략하거나 `any`를 사용하세요. --- # 모델 > Raon이 제공하는 모델의 사양입니다. ## Raon-1 mini preview [#raon-1-mini-preview] | 항목 | 내용 | | --- | --- | | 모델 ID | `raon-1-mini-preview` | | 표시 이름 | Raon-1 mini preview | | 컨텍스트 윈도우 | 262,144 토큰 (입력과 출력 합계) | | 입력 | 텍스트 | | 출력 | 텍스트 (추론 내용은 별도 필드로 반환) | | API | Chat Completions, Responses, Messages | | 도구 | 사용자 코드가 실행하는 함수 도구, Raon이 실행하는 [웹 검색](/ko/docs/web-search) | 모델은 답변을 생성하기 전에 추론합니다. 추론 내용은 API별로 정해진 필드에 답변과 분리되어 반환됩니다. 추론 내용을 확인하고 출력 한도를 설정하는 방법은 [추론](/ko/docs/reasoning)을 참고하세요. 모델은 텍스트 입력만 지원합니다. 요청에 포함한 이미지나 파일은 인식하지 못하므로, 문서는 텍스트로 변환해 보내세요. ## 모델 목록 조회 [#모델-목록-조회] `GET /v1/models`는 API 키로 사용할 수 있는 모델 목록을 반환합니다. 각 항목에는 컨텍스트 윈도우와 요금 정보가 포함됩니다. 토큰 집계와 과금 기준은 [토큰과 사용량](/ko/docs/usage)을 참고하세요. ```bash curl https://raon-api.krafton.ai/v1/models \ -H "Authorization: Bearer $RAON_API_KEY" ``` 프리뷰 모델은 사양이 변경되거나 다른 모델로 교체될 수 있습니다. 모델 ID를 코드 여러 곳에 직접 작성하지 말고, 이 목록에서 조회해 사용하세요. --- # OpenClaw > Raon을 OpenClaw 프로바이더로 등록하고 기본 모델로 설정할지 선택합니다. 설치 스크립트는 Raon을 OpenClaw 프로바이더 `raon`으로 등록하고, 기본 모델로 설정할지 묻습니다. 동의하면 기본 모델을 Raon으로 변경하고, 거절하면 기존 기본 모델을 유지합니다. 다른 프로바이더 설정은 변경하지 않으며, 대화 중 `/model` 명령으로 다른 모델로 전환할 수 있습니다. 기본 모델을 변경할지 묻는 단계에서 Enter 키를 누르면 Raon으로 변경합니다. `--yes` 옵션(Windows는 `-Yes`)을 지정해도 기본 모델을 Raon으로 변경합니다. 사용자 입력을 받을 수 없는 환경에서 이 옵션 없이 실행하면 Raon만 등록하고 기존 기본 모델을 유지합니다. ## 설치 [#설치] 먼저 OpenClaw를 설치하고 온보딩을 완료하세요. 아래 설치 스크립트는 이미 설치된 OpenClaw에 Raon을 추가합니다. ```bash tab="macOS / Linux" curl -fsSL https://raon-console.krafton.ai/setup/openclaw.sh | bash ``` ```powershell tab="Windows (PowerShell)" irm https://raon-console.krafton.ai/setup/openclaw.ps1 | iex ``` 설치 스크립트는 입력받은 API 키로 테스트 요청을 보냅니다. 이어서 `~/.openclaw/.env`에 `RAON_API_KEY`를 저장하고, `~/.openclaw/openclaw.json`에 프로바이더를 추가합니다. 두 파일은 변경 전에 백업합니다. OpenClaw는 `.env` 파일에서 환경 변수 값을 읽을 수 있습니다. 기본 설정에서는 변경된 모델 설정을 자동으로 불러옵니다. 설정 자동 갱신을 꺼 두었다면 설치 후 OpenClaw를 재시작해야 합니다. 셸이나 서비스에 이미 설정된 `RAON_API_KEY` 환경 변수가 `.env`의 값보다 우선 적용될 수 있습니다. 테스트 요청은 성공했는데 OpenClaw에서 인증 오류가 계속 발생하면 해당 환경 변수 값을 확인하세요. 필요한 경우 값을 수정한 뒤 서비스를 재시작하세요. ## 설정 확인 [#설정-확인] ```bash openclaw models list --provider raon ``` 대화 중에는 `/model raon/raon-1-mini-preview` 명령으로 Raon 모델로 전환하고, `/model list` 명령으로 사용할 수 있는 모델 목록을 확인할 수 있습니다. 모델 사용이 허용되지 않았다는 오류가 발생하면 OpenClaw의 모델 허용 정책과 에이전트별 제한을 확인하세요. 설치 스크립트는 기존 정책을 변경하지 않습니다. 따라서 프로바이더를 등록해도 모델 허용 목록에는 자동으로 추가되지 않습니다. ## 수동 설정 [#수동-설정] API 키를 `~/.openclaw/.env` 파일에 저장합니다. ```bash title="~/.openclaw/.env" RAON_API_KEY= ``` 다음 내용을 `~/.openclaw/openclaw.json`의 기존 설정에 병합합니다. ```json5 title="~/.openclaw/openclaw.json" { agents: { defaults: { model: { primary: "raon/raon-1-mini-preview" } }, }, models: { providers: { raon: { baseUrl: "https://raon-api.krafton.ai/v1", apiKey: "${RAON_API_KEY}", api: "openai-completions", models: [ { id: "raon-1-mini-preview", name: "Raon-1 mini preview", reasoning: true, input: ["text"], contextWindow: 262144, maxTokens: 16384, compat: { supportsUsageInStreaming: true }, }, ], }, }, }, } ``` | 항목 | 설명 | | --- | --- | | `primary` | Raon을 기본 모델로 지정. 기존 기본 모델을 유지하고 대화마다 전환하려면 생략 | | `contextWindow` | 필수. 생략하면 OpenClaw가 200,000으로 간주 | | `supportsUsageInStreaming` | 스트리밍 응답의 토큰 사용량 수집 | ## 제거 [#제거] 설치 스크립트가 등록한 Raon 프로바이더와 저장한 API 키를 제거합니다. OpenClaw 프로그램과 다른 프로바이더의 설정, 도구 설정은 유지합니다. 설치 스크립트가 기본 모델을 Raon으로 변경했다면 설치 전 기본 모델로 복원합니다. 설치 후 사용자가 기본 모델을 변경한 경우에는 사용자가 지정한 값을 유지합니다. ```bash tab="macOS / Linux" curl -fsSL https://raon-console.krafton.ai/setup/openclaw.sh | bash -s -- --uninstall ``` ```powershell tab="Windows (PowerShell)" & ([scriptblock]::Create((irm https://raon-console.krafton.ai/setup/openclaw.ps1))) -Uninstall ``` 설치 전에 같은 이름의 Raon 프로바이더나 API 키가 있었다면 원래 값으로 복원합니다. 다만 Raon 프로바이더를 수정했거나 기본 모델 복원 후에도 전역 기본 모델, 대체 모델(fallback), 개별 에이전트의 모델 설정이 Raon을 참조하면 프로바이더와 키를 유지하고 그 이유를 표시합니다. 설치할 때는 Raon을 등록만 하고 나중에 모델로 선택한 경우에도 같은 기준을 적용합니다. 설치 후 변경한 API 키도 삭제하지 않습니다. 제거 스크립트는 설정 파일의 모델 참조를 확인하며, 개별 대화에서 선택한 모델은 확인하지 않습니다. 대화에서도 Raon이 아닌 모델로 전환한 뒤 프로바이더를 제거하세요. 제거할 때는 설치 스크립트가 남긴 기록을 참조합니다. 수동으로 추가한 설정이나 설치 기록이 없는 이전 버전의 설정은 자동으로 제거하지 않습니다. API 키를 입력하거나 API 서버에 연결할 필요는 없습니다. 다만 설정 변경에 에이전트의 명령을 사용하므로 OpenClaw가 설치되어 있어야 합니다. 로컬에 저장한 키를 삭제해도 서버에서 발급한 API 키는 폐기되지 않습니다. --- # 속도 제한 > 분당 요청 수와 토큰 수 한도, 한도 초과 시 동작입니다. 속도 제한은 특정 클라이언트의 과도한 요청이 다른 사용자에게 영향을 주지 않도록 합니다. 한도는 조직 단위로 적용되며, 조직은 워크스페이스별로 더 낮은 한도를 설정할 수 있습니다. 현재 한도는 콘솔의 **용량** 화면에서 확인할 수 있습니다. ## 제한 항목 [#제한-항목] 각 한도는 1분 단위로 집계하며, 제한 항목은 다음과 같습니다. | 항목 | 집계 대상 | | --- | --- | | 분당 요청 수(RPM) | 수신한 요청 수 | | 분당 입력 토큰 수 | 모델에 전달한 입력 토큰 | | 분당 출력 토큰 수 | 모델이 생성한 출력 토큰 (추론 토큰 포함) | Raon은 요청을 받으면 모델이 답변을 생성하기 전에 한도를 확인합니다. 입력 토큰 수는 요청 크기를 기준으로 추정합니다. 출력 토큰 수는 요청에 지정한 최대값(`max_tokens`, `max_completion_tokens`, `max_output_tokens`)만큼 한도에서 미리 차감합니다. 이를 토큰 예약이라고 하며, 요청에 최대값을 지정하지 않으면 기본값을 사용합니다. 모델 서버에서 사용량을 받으면 예약한 토큰 수를 실제 사용량에 맞게 조정합니다. 이때 캐시에서 읽은 토큰은 입력 토큰 한도 계산에서 제외합니다. 사용량을 받지 못한 경우에는 요청 처리 결과에 따라 예약을 유지하거나 해제합니다. 정상적으로 완료된 요청은 예약한 토큰 수를 그대로 유지합니다. 스트림이 중단되면 출력 토큰 예약만 해제하고 입력 토큰 예약은 유지합니다. 토큰 예약을 조정해도 분당 요청 수(RPM) 집계에서 해당 요청을 제외하지는 않습니다. `max_tokens`를 필요 이상으로 크게 지정하면 사용하지 않을 출력 토큰까지 예약되어 출력 한도에 일찍 도달할 수 있습니다. 예상되는 최대 답변 길이에 추론 분량을 더한 정도로 설정하세요. ## 응답 헤더 [#응답-헤더] RPM 한도가 적용된 경우 성공한 응답과 `rate_limit_exceeded` 오류에 다음 헤더가 포함됩니다. 인증 오류와 `overloaded` 오류에는 포함되지 않습니다. | 헤더 | 설명 | | --- | --- | | `x-ratelimit-limit-requests` | 1분당 허용 요청 수 | | `x-ratelimit-remaining-requests` | 현재 1분 구간에 남은 요청 수 | | `x-ratelimit-reset-requests` | 현재 구간이 초기화되는 시각 (Unix 타임스탬프, 초 단위) | ## 한도를 초과한 경우 [#한도를-초과한-경우] | 상태 코드 | `code` | 설명 | | --- | --- | --- | | 429 | `rate_limit_exceeded` | 분당 한도 초과. `retry-after`에 현재 구간이 끝날 때까지 남은 시간(초) 포함 | | 429 | `overloaded` | 서비스 과부하. 잠시 후 재시도 (`retry-after`는 보통 2초) | | 400 | `token_limit_exceeded` | 단일 요청 크기가 분당 토큰 한도 초과. 재시도로 해결되지 않으므로 입력 또는 `max_tokens` 축소 필요 | | 402 | `insufficient_credit` | 조직의 크레딧 부족 | | 402 | `spend_limit_exceeded` | 조직 또는 워크스페이스의 월 지출 한도 도달 | Messages API에서는 게이트웨이가 생성한 위 오류를 `code` 필드 없이 반환하며, `type` 필드로 오류를 구분합니다(`rate_limit_error` 또는 `invalid_request_error`). 모델 서버에서 발생한 입력 검증 오류는 다른 [오류 형식](/ko/docs/errors)으로 전달될 수 있습니다. 이번 프리뷰의 모델 이용 요금은 0원이지만 토큰 한도는 적용됩니다. 이용 요금과는 별도로 조직의 크레딧과 지출 한도를 확인하는 정책도 적용됩니다. HTTP 402 오류가 발생하면 프리뷰 운영자에게 문의하세요. 테스터는 지출 설정 화면에 접근할 수 없습니다. ## 재시도 [#재시도] 429 오류가 발생하면 `retry-after`에 지정된 시간만큼 기다린 후 재시도하고, 실패할 때마다 대기 시간을 늘리세요(지수 백오프). OpenAI SDK와 Anthropic SDK는 이 방식을 기본으로 지원하며, `retry-after`에 따라 최대 2회 재시도합니다. 요청을 대량으로 보낸다면 재시도 횟수를 늘리세요. ```python tab="OpenAI SDK" client = OpenAI( base_url="https://raon-api.krafton.ai/v1", api_key=os.environ["RAON_API_KEY"], max_retries=5, ) ``` ```python tab="Anthropic SDK" client = Anthropic( base_url="https://raon-api.krafton.ai", api_key=os.environ["RAON_API_KEY"], max_retries=5, ) ``` 재시도에 의존하지 않고 한도 내에서 사용하려면 동시에 실행하는 요청 수를 제한하세요. --- # 추론 > 모델의 추론 내용을 확인하고 답변에 필요한 출력 토큰 수를 설정합니다. `raon-1-mini-preview`는 답변을 생성하기 전에 추론합니다. 추론 내용은 API별로 다음 위치에 답변과 분리되어 반환됩니다. | API | 추론 내용 위치 | | --- | --- | | Chat Completions | `message.reasoning` (스트리밍에서는 `delta.reasoning`) | | Responses | `output`의 `reasoning` 항목 | | Messages | `thinking` 콘텐츠 블록 | ## 추론과 max_tokens [#추론과-max_tokens] 추론 토큰도 최대 출력 토큰 수(`max_tokens`, `max_completion_tokens`, `max_output_tokens`)에 포함됩니다. 추론 중에 출력 한도에 도달하면 답변이 비어 있을 수 있습니다. 이 경우 API별로 다음 필드를 확인하세요. | API | 출력 한도에 도달했을 때의 응답 | | --- | --- | | Chat Completions | `finish_reason: "length"` | | Messages | `stop_reason: "max_tokens"` | | Responses | `status: "incomplete"`와 원인을 설명하는 `incomplete_details` | 추론과 답변을 모두 생성할 수 있도록 출력 한도를 충분히 지정하세요. ## 항상 활성화 [#항상-활성화] Raon은 항상 답변 전에 추론하며, 추론을 비활성화할 수 없습니다. API는 호환성을 위해 `chat_template_kwargs.enable_thinking`을 허용하지만, `false`를 포함한 모든 값을 무시합니다. ## 추론 강도 [#추론-강도] 추론은 비활성화할 수 없으며, 강도나 토큰 한도도 조절할 수 없습니다. 다음 파라미터는 오류 없이 허용되지만 결과에는 반영되지 않습니다. | API | 허용되지만 반영되지 않는 파라미터 | | --- | --- | | Chat Completions | `reasoning_effort` | | Responses | `reasoning.effort` | | Messages | `thinking` (`type: "disabled"`, `budget_tokens` 포함) | --- # Responses > OpenAI Responses 형식의 API입니다. POST /v1/responses로 호출합니다. SDK는 `pip install openai` 또는 `npm install openai` 명령으로 설치합니다. 시스템 프롬프트는 `instructions` 파라미터로 지정합니다. ```bash tab="curl" curl https://raon-api.krafton.ai/v1/responses \ -H "Authorization: Bearer $RAON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "raon-1-mini-preview", "instructions": "You are a helpful assistant.", "input": "Hello!"}' ``` ```python tab="Python" import os from openai import OpenAI client = OpenAI( base_url="https://raon-api.krafton.ai/v1", api_key=os.environ["RAON_API_KEY"], ) response = client.responses.create( model="raon-1-mini-preview", instructions="You are a helpful assistant.", input="Hello!", ) print(response.output_text) ``` ```ts tab="TypeScript" import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://raon-api.krafton.ai/v1", apiKey: process.env.RAON_API_KEY, }); const response = await client.responses.create({ model: "raon-1-mini-preview", instructions: "You are a helpful assistant.", input: "Hello!", }); console.log(response.output_text); ``` 모델의 추론 내용은 `output` 배열에서 `message` 항목 앞에 `reasoning` 항목으로 반환됩니다. 답변이 `max_output_tokens`에 도달하면 `status`는 `incomplete`, `incomplete_details.reason`은 `max_output_tokens`가 됩니다. ## 응답 저장 미지원 [#응답-저장-미지원] OpenAI의 `store`는 응답을 서버에 저장해 두고, 다음 요청에서 `previous_response_id`로 이어서 사용하는 기능입니다. Raon은 이 기능을 지원하지 않습니다. `store`는 항상 `false`로 처리되며, 저장된 상태를 참조하는 요청은 거부됩니다. 요청할 때마다 이전 답변을 포함한 전체 대화를 `input`에 담아 보내세요. 지원하지 않는 요청의 전체 목록은 [지원하지 않는 요청](/ko/docs/limits)을 참고하세요. --- # SDK와 프레임워크 > OpenAI·Anthropic SDK, LangChain, Vercel AI SDK를 Raon에 연결합니다. Raon이 지원하는 텍스트 생성 기능은 OpenAI와 Anthropic의 공식 SDK로 호출할 수 있습니다. Base URL, API 키, 모델 ID를 설정하세요. 다른 API 서비스를 사용하던 코드를 Raon에 연결할 때는 [지원 기능과 제한](/ko/docs/limits)도 확인하세요. API 형식이 같아도 해당 서비스의 모든 기능을 지원하는 것은 아닙니다. | 클라이언트 | Base URL | API 키 파라미터 | | --- | --- | --- | | OpenAI SDK와 이를 기반으로 한 프레임워크 | `https://raon-api.krafton.ai/v1` | `api_key` / `apiKey` | | Anthropic SDK | `https://raon-api.krafton.ai` (`/v1`은 SDK가 자동 추가) | `api_key` / `apiKey` | ## OpenAI SDK [#openai-sdk] ```python tab="Python" # pip install openai import os from openai import OpenAI client = OpenAI( base_url="https://raon-api.krafton.ai/v1", api_key=os.environ["RAON_API_KEY"], ) ``` ```ts tab="TypeScript" // npm install openai import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://raon-api.krafton.ai/v1", apiKey: process.env.RAON_API_KEY, }); ``` 하나의 클라이언트로 [Chat Completions](/ko/docs/chat-completions)와 [Responses](/ko/docs/responses)를 모두 호출할 수 있습니다. ## Anthropic SDK [#anthropic-sdk] ```python tab="Python" # pip install anthropic import os from anthropic import Anthropic client = Anthropic( base_url="https://raon-api.krafton.ai", api_key=os.environ["RAON_API_KEY"], ) ``` ```ts tab="TypeScript" // npm install @anthropic-ai/sdk import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ baseURL: "https://raon-api.krafton.ai", apiKey: process.env.RAON_API_KEY, }); ``` 이 클라이언트로 [Messages](/ko/docs/messages)를 호출할 수 있습니다. ## LangChain [#langchain] `ChatOpenAI`에 Raon의 Base URL을 지정합니다. ```python # pip install langchain-openai import os from langchain_openai import ChatOpenAI llm = ChatOpenAI( model="raon-1-mini-preview", base_url="https://raon-api.krafton.ai/v1", api_key=os.environ["RAON_API_KEY"], ) print(llm.invoke("Hello!").content) ``` ## Vercel AI SDK [#vercel-ai-sdk] OpenAI 호환 프로바이더를 사용합니다. 모델의 추론 내용은 `reasoningText`로 받을 수 있습니다. ```ts // npm install ai @ai-sdk/openai-compatible import { createOpenAICompatible } from "@ai-sdk/openai-compatible"; import { generateText } from "ai"; const raon = createOpenAICompatible({ name: "raon", baseURL: "https://raon-api.krafton.ai/v1", apiKey: process.env.RAON_API_KEY, }); const { text } = await generateText({ model: raon("raon-1-mini-preview"), prompt: "Hello!", }); console.log(text); ``` ## OpenAI·Anthropic 코드에서 전환하기 [#openaianthropic-코드에서-전환하기] 기존 OpenAI·Anthropic 코드를 Raon으로 전환할 때 달라지는 점은 다음과 같습니다. | 항목 | 내용 | | --- | --- | | 모델 ID | `raon-1-mini-preview` 사용. `gpt-4o`, `claude-sonnet-4-5` 등 다른 서비스의 모델 이름은 403 `model_not_allowed` 반환 | | 요청 파라미터 | 모든 생성 API에서 응답 안정성을 위해 `temperature=1.0`, `top_p=0.95`, `top_k=20`, `presence_penalty=1.5`, `repetition_penalty=1.0`, `frequency_penalty=0`, `min_p=0`으로 고정합니다. 값을 생략하거나 null 또는 다른 값을 보내도 동일합니다. `stop`, `seed`, `response_format` 등은 모델에 그대로 전달합니다. 추론 강도 설정은 허용하지만 반영하지 않습니다([추론](/ko/docs/reasoning) 참고). | | 대화 상태 | 서버에 저장하지 않음. `store`는 항상 비활성화되며 요청마다 전체 대화 전송 필요 ([지원하지 않는 요청](/ko/docs/limits) 참고) | | 도구 | 함수 도구는 세 API 모두 지원. 서버 실행 도구는 [웹 검색](/ko/docs/web-search)만 지원 | | 입력 형식 | 텍스트만 지원. 이미지, 오디오, 파일 미지원 | --- # 스트리밍 > 생성되는 답변을 서버 전송 이벤트(SSE)로 실시간 수신합니다. 세 API 모두 `stream`을 `true`로 설정하면 답변이 생성되는 대로 서버 전송 이벤트(SSE)로 전달됩니다. Python 예제는 [Chat Completions](/ko/docs/chat-completions)나 [Messages](/ko/docs/messages)에서 만든 클라이언트를 사용합니다. ```python tab="Chat Completions" stream = client.chat.completions.create( model="raon-1-mini-preview", messages=[{"role": "user", "content": "Hello!"}], stream=True, stream_options={"include_usage": True}, ) for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True) ``` ```python tab="Responses" stream = client.responses.create(model="raon-1-mini-preview", input="Hello!", stream=True) for event in stream: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True) ``` ```python tab="Messages" with client.messages.stream( model="raon-1-mini-preview", max_tokens=1024, messages=[{"role": "user", "content": "Hello!"}], ) as stream: for text in stream.text_stream: print(text, end="", flush=True) ``` ```bash tab="curl" curl -N https://raon-api.krafton.ai/v1/chat/completions \ -H "Authorization: Bearer $RAON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "raon-1-mini-preview", "stream": true, "messages": [{"role": "user", "content": "Hello!"}]}' ``` - Chat Completions에서 `stream_options.include_usage`를 설정하면 마지막 청크에 토큰 사용량이 포함됩니다. - curl로 확인할 때는 출력이 버퍼링되지 않도록 `-N` 옵션을 추가하세요. --- # 구조화된 출력 > 지정한 JSON 스키마에 맞춰 답변을 생성합니다. JSON 스키마를 지정하면 모델이 해당 스키마를 따르는 JSON으로 답변합니다. 텍스트에서 정보를 추출하거나 양식을 채우는 등 코드에서 답변을 파싱해야 할 때 사용합니다. ## 스키마 지정 [#스키마-지정] OpenAI SDK는 Pydantic 모델이나 Zod 객체로 스키마를 생성하고 답변 파싱까지 처리합니다. ```python tab="Chat Completions" from pydantic import BaseModel class Person(BaseModel): name: str age: int completion = client.chat.completions.parse( model="raon-1-mini-preview", messages=[{"role": "user", "content": "Make up a person who lives in Seoul."}], response_format=Person, ) print(completion.choices[0].message.parsed) ``` ```python tab="Responses" from pydantic import BaseModel class Person(BaseModel): name: str age: int response = client.responses.parse( model="raon-1-mini-preview", input="Make up a person who lives in Seoul.", text_format=Person, ) print(response.output_parsed) ``` ```bash tab="curl" curl https://raon-api.krafton.ai/v1/chat/completions \ -H "Authorization: Bearer $RAON_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "raon-1-mini-preview", "messages": [{"role": "user", "content": "Make up a person who lives in Seoul."}], "response_format": { "type": "json_schema", "json_schema": { "name": "person", "strict": true, "schema": { "type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "integer"}}, "required": ["name", "age"], "additionalProperties": false } } } }' ``` | API | 스키마 지정 위치 | | --- | --- | | Chat Completions | `response_format: {"type": "json_schema", "json_schema": {...}}` | | Responses | `text.format: {"type": "json_schema", "name": ..., "schema": {...}}` | | Messages | `output_config: {"format": {"type": "json_schema", "schema": {...}}}` | 구조화된 출력을 사용해도 모델은 먼저 추론합니다. 추론 내용은 별도 필드로 반환되며, 스키마는 답변에만 적용됩니다. ## JSON 모드 [#json-모드] Chat Completions에서 `response_format: {"type": "json_object"}`를 지정하면 스키마 없이 유효한 JSON 객체로 답변합니다. 필요한 키는 프롬프트에 명시하세요. ## 권장 사항 [#권장-사항] - 필드 이름은 의미가 명확하게 짓고, 이름만으로 의미가 모호하면 `description`을 추가하세요. 모델은 이 정보를 바탕으로 필드 값을 생성합니다. - 추론과 JSON 답변을 모두 생성할 수 있도록 출력 한도를 충분히 지정하세요. Chat Completions는 `max_tokens` 또는 `max_completion_tokens`, Messages는 `max_tokens`, Responses는 `max_output_tokens`를 사용합니다. - 출력 한도에 도달해 답변이 중간에 끊겼는지 확인하세요. Chat Completions는 `finish_reason: "length"`, Messages는 `stop_reason: "max_tokens"`, Responses는 `status: "incomplete"`와 `incomplete_details`로 확인할 수 있습니다. 답변을 사용하기 전에 JSON을 파싱하고 스키마에 맞는지 검증하세요. --- # 도구 호출 > 사용자 코드에서 실행하는 함수를 모델이 호출하도록 합니다. `tools`에 함수를 정의합니다. 모델이 함수 호출이 필요하다고 판단하면 텍스트 대신 도구 호출을 반환합니다. 사용자 코드에서 함수를 실행한 후, 그 결과를 다음 요청에 포함해 보냅니다. Raon은 도구 정의를 그대로 모델에 전달하며, [웹 검색](/ko/docs/web-search)을 제외한 도구는 직접 실행하지 않습니다. ```python import json tools = [{ "type": "function", "function": { "name": "get_weather", "description": "Current weather for a city", "parameters": { "type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"], }, }, }] messages = [{"role": "user", "content": "What is the weather in Seoul?"}] completion = client.chat.completions.create(model="raon-1-mini-preview", messages=messages, tools=tools) message = completion.choices[0].message if message.tool_calls: messages.append(message) for call in message.tool_calls: args = json.loads(call.function.arguments) result = {"city": args["city"], "temperature_c": 18} # your function here messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)}) completion = client.chat.completions.create(model="raon-1-mini-preview", messages=messages, tools=tools) print(completion.choices[0].message.content) ``` Responses(`function_call`, `function_call_output` 항목)와 Messages(`tool_use`, `tool_result` 블록)도 각 API 형식에 맞춰 같은 방식으로 사용합니다. ## 권장 사항 [#권장-사항] - 함수와 파라미터 설명은 명확하게 작성하세요. 모델은 이 설명을 바탕으로 사용할 도구를 선택합니다. - 일부 에이전트는 매 턴 도구 호출을 기대합니다. 에이전트가 항상 도구를 사용해야 한다면 시스템 프롬프트에 명시하세요. - Messages의 `tool_choice`는 `auto`, `any`, `none`을 지원합니다. 특정 도구를 지정하면 400 오류가 반환됩니다. --- # 토큰과 사용량 > 토큰 집계 방식, API별 사용량 필드와 무료 프리뷰를 안내합니다. 모델은 텍스트를 토큰 단위로 처리합니다. 이번 프리뷰의 모델 이용 요금은 **0원**입니다. 무료로 이용하는 동안에도 [속도 제한](/ko/docs/rate-limits)과 컨텍스트 윈도우(262,144 토큰)의 크기 제한은 적용됩니다. ## 토큰 수 추정 [#토큰-수-추정] `raon-1-mini-preview`의 대략적인 토큰 비율은 다음과 같습니다. | 언어 | 토큰 비율 | | --- | --- | | 한국어 | 약 2~3자당 1토큰 | | 영어 | 약 1단어당 1토큰 | 위 값은 추정치입니다. 정확한 토큰 수는 각 응답의 `usage` 필드에서 확인하세요. ## 응답의 사용량 필드 [#응답의-사용량-필드] | API | 입력 토큰 | 출력 토큰 | 추론 토큰(출력에 포함) | | --- | --- | --- | --- | | Chat Completions | `usage.prompt_tokens` | `usage.completion_tokens` | `usage.completion_tokens_details.reasoning_tokens` | | Responses | `usage.input_tokens` | `usage.output_tokens` | `usage.output_tokens_details.reasoning_tokens` | | Messages | `usage.input_tokens` | `usage.output_tokens` | 별도 표시 없음 | 추론 토큰은 답변과 함께 출력 토큰으로 집계됩니다. 따라서 최대 출력 토큰 수를 지정할 때는 추론에 사용할 토큰 수도 고려해야 합니다. API에 따라 `max_tokens`, `max_completion_tokens`, `max_output_tokens`로 한도를 지정합니다. [추론](/ko/docs/reasoning)은 항상 활성화됩니다. Messages는 캐시에서 읽은 입력 토큰 수와 캐시 생성에 사용한 입력 토큰 수를 각각 `cache_read_input_tokens`, `cache_creation_input_tokens`에 표시합니다. 이 토큰들은 `input_tokens`에 포함되지 않습니다. Chat Completions와 Responses는 전체 입력 토큰 수에 캐시 입력을 포함하며, 캐시 사용량 정보가 있으면 별도 필드로도 표시합니다. 스트리밍 응답에서는 사용량이 마지막에 전달됩니다. Chat Completions는 `stream_options.include_usage`를 설정하면 마지막 청크에, Responses는 `response.completed` 이벤트에, Messages는 `message_start`와 `message_delta` 이벤트에 포함됩니다. 스트림이 중단되면 최종 사용량을 받지 못할 수 있습니다. Raon은 모델 서버가 보고한 사용량을 우선 사용합니다. 보고된 사용량이 없으면 입력 텍스트와 수신한 출력 텍스트를 기준으로 추정합니다. 추정치는 모델이 실제로 처리한 토큰 수와 다를 수 있습니다. 웹 검색 중 모델을 여러 번 호출하면 각 호출의 사용량을 합산합니다. ## 요금 [#요금] `GET /v1/models`는 100만 토큰당 단가를 미국 달러(USD) 단위로 반환합니다. ```json "pricing": { "input_per_mtok": "…", "output_per_mtok": "…", "cache_read_per_mtok": "…", "cache_write_per_mtok": "…" } ``` 모델 이용 요금은 일반 입력·캐시 읽기·캐시 쓰기·출력 토큰 수에 각각 해당 단가를 적용해 계산합니다. 캐시를 사용하지 않은 요청은 입력 토큰 비용과 출력 토큰 비용을 합산합니다. 오류 상태 코드로 응답한 요청에는 요금을 부과하지 않습니다. 정상적으로 시작된 스트림은 중단되더라도 사용량이 기록될 수 있습니다. 이번 프리뷰에서는 모델 이용 요금이 0원이므로 이 경우에도 요금이 발생하지 않습니다. --- # 웹 검색 > 모델이 웹을 검색하고 출처를 포함해 답변합니다. 웹 검색은 Raon 서버에서 수행합니다. 서버에 검색 기능이 설정되어 있고 소속 조직에서 사용을 허용한 경우에 이용할 수 있습니다. 요청에 다음 옵션을 추가하세요. | API | 활성화 방법 | | --- | --- | | Chat Completions | `web_search_options` 추가 | | Responses | `web_search` 도구 추가 | | Messages | `web_search_20250305` 같은 `web_search_*` 도구 추가 | 검색 여부와 시점은 모델이 판단하며, 답변 전에 여러 번 검색할 수도 있습니다. 검색과 추가 모델 호출로 응답 시간이 늘어날 수 있습니다. `max_uses`를 지정해도 서버에서 정한 검색 한도를 넘을 수는 없습니다. 검색 중 오류가 발생하거나 한도에 도달하면 더 검색하지 않고 답변할 수 있습니다. 응답의 `usage`는 마지막 모델 호출의 토큰입니다. 이 호출에는 대화 전체와 모든 검색 결과가 한 번씩 들어 있습니다. 청구되는 토큰도 이 값이며, input 토큰 수는 다음 요청을 보낼 때의 대화 크기와 같습니다. ```python tab="Chat Completions" completion = client.chat.completions.create( model="raon-1-mini-preview", web_search_options={"search_context_size": "medium"}, messages=[{"role": "user", "content": "What changed in the latest PUBG update?"}], ) message = completion.choices[0].message print(message.content) for annotation in message.annotations or []: print(annotation.url_citation.title, annotation.url_citation.url) ``` ```python tab="Responses" response = client.responses.create( model="raon-1-mini-preview", tools=[{"type": "web_search"}], input="What changed in the latest PUBG update?", ) print(response.output_text) for item in response.output: if item.type == "message": for part in item.content: if part.type == "output_text": for annotation in part.annotations: print(annotation.title, annotation.url) ``` ```python tab="Messages" message = client.messages.create( model="raon-1-mini-preview", max_tokens=2048, tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 3}], messages=[{"role": "user", "content": "What changed in the latest PUBG update?"}], ) for block in message.content: if block.type == "text": print(block.text) for citation in block.citations or []: print(" -", citation.title, citation.url) print(message.usage.server_tool_use.web_search_requests) ``` ```bash tab="curl" curl https://raon-api.krafton.ai/v1/chat/completions \ -H "Authorization: Bearer $RAON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model": "raon-1-mini-preview", "web_search_options": {}, "messages": [{"role": "user", "content": "What changed in the latest PUBG update?"}]}' ``` ## Chat Completions와 Responses [#chat-completions와-responses] - `search_context_size`는 검색 1회당 결과 수를 지정합니다(`low` 3개, `medium` 5개, `high` 10개). - 출처는 `url_citation` 어노테이션으로 반환됩니다. Chat Completions에서는 `message.annotations`에, 스트리밍에서는 마지막 청크의 `delta.annotations`에 포함됩니다. - Responses에서는 검색할 때마다 `web_search_call` 출력 항목이 추가됩니다. `filters.allowed_domains`를 지정하면 해당 사이트의 결과만 사용합니다. ## Messages [#messages] | 항목 | 설명 | | --- | --- | | 응답 블록 | 검색마다 `server_tool_use`, `web_search_tool_result` 블록 추가 | | 출처 | 답변 `text` 블록의 `citations` (`web_search_result_location` 형식) | | 검색 제한 | `max_uses`로 검색 횟수 제한, `allowed_domains`·`blocked_domains`로 검색 사이트 제한 | | 검색 횟수 | `usage.server_tool_use.web_search_requests` | | `tool_choice` | 생략 또는 `auto`, `any`, `none` 사용. 특정 도구 강제(`type: "tool"`) 시 400 오류 | --- # 개요 > 엔드포인트별 파라미터, 요청·응답 형식과 예시를 설명합니다. API 레퍼런스는 Raon의 OpenAPI 명세를 바탕으로 엔드포인트별 파라미터, 응답, 오류를 설명합니다. 요청 예시는 `https://raon-api.krafton.ai`를 기준으로 합니다. - 요청은 `Authorization: Bearer ` 헤더로 인증합니다. Messages API는 `x-api-key` 헤더도 지원합니다. - 세 추론 API는 OpenAI와 Anthropic 형식을 따릅니다. Raon에서 동작이 달라지는 부분은 각 API 페이지를 참고하세요. 지원 범위는 [지원하지 않는 기능과 요청](/ko/docs/limits)에서 확인할 수 있습니다. - 스키마의 필드 이름 옆에 `*`가 있으면 필수 항목이며, `?`가 있으면 생략할 수 있는 항목입니다. 자료형, 기본값, 값의 허용 범위도 함께 확인하세요.