# Chat Completions > The OpenAI Chat Completions format, at POST /v1/chat/completions. Install the SDK with `pip install openai` or `npm install openai`. The system prompt is the first item of `messages`, with `role: "system"`; it sets the model's role, tone and rules. ```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); ``` The answer is in `message.content`. The model's reasoning comes separately in `message.reasoning`. `finish_reason` says why the answer ended: `stop` when it is complete, `tool_calls` when the model wants a [tool](/en/docs/tool-calling), and `length` when it reached `max_tokens`. Reasoning counts toward that limit, so a low `max_tokens` can leave the answer empty; see [Reasoning](/en/docs/reasoning#reasoning-and-max_tokens). ## Conversations [#conversations] Raon keeps no conversation on the server. Send the whole conversation in `messages` on every turn, and append each answer as an `assistant` message. Leave the reasoning out of the history; the model does not need it back. ## Related [#related] - [Streaming](/en/docs/streaming), [structured outputs](/en/docs/structured-outputs), [web search](/en/docs/web-search) and [tool calling](/en/docs/tool-calling) on this API. - Every parameter is in the [API reference](/en/docs/api-reference). --- # Claude Code > Run Claude Code on Raon with a separate command, keeping your own Claude setup. The installer adds a `raon-claude` command that runs Claude Code on Raon. Plain `claude` and `~/.claude/settings.json` stay as they are, so your own account keeps working. ## Install [#install] ```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 ``` The installer installs Claude Code if it is missing, asks for your API key, makes a test call, and writes two files: | File | What it holds | | --- | --- | | `~/.raon/claude-code.json` | The Raon settings, readable only by you | | `~/.local/bin/raon-claude` | The command, which starts `claude --settings ~/.raon/claude-code.json` | If an earlier installer changed `~/.claude/settings.json`, running it again puts your own values back. ## Start [#start] ```bash raon-claude raon-claude -p "Explain this repository" ``` ## Set up by hand [#set-up-by-hand] Save this as `~/.raon/claude-code.json`, readable only by you: ```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" } } ``` Start Claude Code with that file. It overrides `~/.claude/settings.json` in that session only: ```bash claude --settings ~/.raon/claude-code.json ``` - `ANTHROPIC_BASE_URL` has no `/v1`; Claude Code adds it. - Every model alias points at the Raon model, so background calls and subagents never ask for a Claude model. - Claude Code WebSearch requests that force a named tool (`tool_choice.type: "tool"`) are not supported and return 400. ## Remove [#remove] Remove the Raon-specific settings, key, and launcher. The agent itself stays installed, and the API key is not revoked on the server. See [installer options](/en/docs/installer-options#uninstall) for removal details for all four agents. ```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 > Run Codex on Raon with a separate profile and command, keeping your own Codex setup. The installer adds a `raon` Codex profile and a `raon-codex` command that runs Codex on Raon. Plain `codex` and `~/.codex/config.toml` stay as they are. ## Install [#install] ```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 ``` The installer needs Codex 0.134.0 or later and offers to install or update it. It asks for your API key, makes a test call, and writes: | File | What it holds | | --- | --- | | `~/.codex/raon.config.toml` | The `raon` profile, with its own model provider | | `~/.codex/raon.key` | Your API key, readable only by you | | `~/.local/bin/raon-codex` | The command, which starts `codex --profile raon` | `CODEX_HOME`, when set, is used instead of `~/.codex`. If an earlier installer changed `config.toml`, running it again puts your own values back. ## Start [#start] ```bash raon-codex raon-codex exec "Explain this repository" codex --profile raon # the same, without the command ``` Web search works with Codex's default setting. If your organization has web search turned off, set `web_search = "disabled"`. Do not turn on `apply_patch` as a freeform custom tool. Raon's backend cannot read those calls back. ## Set up by hand [#set-up-by-hand] Save this as `~/.codex/raon.config.toml` and keep your key in `RAON_API_KEY`. Plain `codex` does not read this file; `codex --profile raon` does: ```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" ``` Keep `model_context_window` at 262144 or lower, the model's context window. ## Remove [#remove] Remove the Raon-specific settings, key, and launcher. The agent itself stays installed, and the API key is not revoked on the server. See [installer options](/en/docs/installer-options#uninstall) for removal details for all four agents. ```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 ``` --- # Other compatible tools > Connect any tool that takes a custom OpenAI-compatible provider. Most coding agents and chat apps can add a custom OpenAI-compatible provider, such as opencode, pi, Cline and Continue. Enter these values in the tool's provider settings: | Setting | Value | | --- | --- | | API type | OpenAI-compatible, Chat Completions | | Base URL | `https://raon-api.krafton.ai/v1` | | API key | Your key, read from the `RAON_API_KEY` environment variable where the tool allows it | | Model ID | `raon-1-mini-preview` | | Context window | 262144 | | Max output tokens | 16384 is a good start; reasoning counts toward it | | Reasoning | Always on; caller controls are ignored. The reasoning arrives in `message.reasoning`. | | Input | Text only | ## Example: opencode [#example-opencode] Add a provider to `opencode.json`, in your project or in `~/.config/opencode/`: ```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` makes Raon the default. Without it, pick the model with `/models` inside opencode. ## When something does not work [#when-something-does-not-work] - A 404 on every request usually means the base URL is missing `/v1`, or has it twice. - An empty answer usually means the output limit is too low for the reasoning; raise it. - Tools that only speak the Anthropic format can use `https://raon-api.krafton.ai` as their base URL, without `/v1`; see [Messages](/en/docs/messages). --- # Errors > Error statuses and shapes, which ones to retry, and how long a request can take. ## Error shape [#error-shape] Gateway-generated errors follow each API's own format. Chat Completions, Responses and `GET /v1/models` return: ```json { "error": { "message": "Incorrect API key provided.", "type": "authentication_error", "param": null, "code": "invalid_api_key" } } ``` For errors generated by the gateway, Messages returns the Anthropic format, which has `type` but no `code`: ```json { "type": "error", "error": { "type": "authentication_error", "message": "Incorrect API key provided." } } ``` The SDKs turn these into exceptions, such as `openai.AuthenticationError` and `anthropic.RateLimitError`. Model server validation errors can be relayed in a different format. For example, a Messages request can receive an HTTP 400 body with `error.type: "upstream_error"` and `error.code: "upstream_http_error"`, without a top-level `type`. An unexpected internal failure can also use an OpenAI-style envelope. Inspect the HTTP status and full error body rather than assuming every Messages error has the shape above. ## Status codes [#status-codes] | Status | `code` | Cause | Retry? | | --- | --- | --- | --- | | 400 | `invalid_request` | The body is not valid JSON, misses a required field, or uses a [refused feature](/en/docs/limits). | No. Fix the request. | | 400 | `unsupported_tool` | A tool Raon does not run, such as `code_interpreter`. | No | | 400 | `token_limit_exceeded` | One request exceeds a per-minute token limit. | No | | 400 | — | The input and `max_tokens` together exceed the context window. | No. Shorten the input. | | 401 | `invalid_api_key` | The key is missing, wrong, disabled or expired. | No | | 402 | `insufficient_credit`, `spend_limit_exceeded` | No credit left, or the monthly spend limit is reached. | No | | 403 | `model_not_allowed` | The model ID is wrong, or your key cannot use that model. | No | | 404 | — | The path is not served, often a base URL with a missing or doubled `/v1`. | No | | 413 | `payload_too_large` | The body is over 28 MiB. | No | | 429 | `rate_limit_exceeded`, `overloaded` | See [Rate limits](/en/docs/rate-limits). | Yes, after `retry-after` | | 500 | — | An error inside Raon. | Yes, with backoff | | 502 | `upstream_error` | The model server failed or did not answer in time. | Yes, with backoff | Retry with growing waits, and stop after a few attempts. Do not retry 4xx errors other than 429; the same request fails the same way. The model price is zero during this preview. A 402 still indicates an organization policy check; contact the preview operator rather than looking for a payment or spend-settings page. ## Errors during a stream [#errors-during-a-stream] A streamed response has already sent 200 when it starts, so an error after that arrives as an event in the stream: | API | Error event | | --- | --- | | Chat Completions | a `data:` line holding `{"error": {...}}` | | Responses | `event: error` | | Messages | `event: error`, in the Anthropic format | The SDKs raise these as exceptions while you iterate. Text received before the error is incomplete; send the request again if you need the whole answer. ## Timeouts [#timeouts] Reasoning and web search can make an answer take minutes. Raon gives a request up to 10 minutes; set your client's timeout to at least that. The OpenAI and Anthropic SDKs wait 10 minutes by default. - Streaming shows progress sooner and keeps the connection busy. When the model is silent for 10 seconds, for example during a web search, Raon sends a `: ping` comment line, which SSE clients skip. - If your client disconnects, Raon stops the request. - Requests must state their size in `Content-Length`. The SDKs and curl do; a chunked upload without it returns 411. ## Reporting a problem [#reporting-a-problem] Include the request time, the response's `x-request-id` header, status code, and error body. Raon generates this tracking UUID for each request, including streamed responses. A client-supplied `x-request-id` does not override it. --- # Troubleshooting > Common problems and how to fix them. ## The answer is empty [#the-answer-is-empty] `content` is empty or `null`, and `finish_reason` is `length` (`stop_reason: "max_tokens"` on Messages, `status: "incomplete"` on Responses). The model spent the whole `max_tokens` on reasoning before it could answer. Raise `max_tokens` to leave room for both [reasoning](/en/docs/reasoning) and the answer. A hard question can take several thousand tokens of reasoning. ## Every request returns 404 [#every-request-returns-404] The base URL is off by `/v1`. The OpenAI SDKs and most OpenAI-compatible tools need `https://raon-api.krafton.ai/v1`. The Anthropic SDKs and Claude Code need `https://raon-api.krafton.ai`, because they add `/v1` themselves. ## 403 `model_not_allowed` [#403-model_not_allowed] The model ID is not one your key can use. Use `raon-1-mini-preview`, not another provider's model name; `GET /v1/models` lists the IDs your key accepts. ## 401 `invalid_api_key` [#401-invalid_api_key] Check that the key is sent, and that it has not been deleted or expired on the console's API keys page. On Chat Completions and Responses the header is `Authorization: Bearer `; on Messages `x-api-key` also works. ## The request takes long or times out [#the-request-takes-long-or-times-out] Reasoning and web search add time, sometimes minutes. Stream the answer to see progress, set the client timeout to at least 10 minutes, and leave enough output tokens for reasoning and the answer. See [Timeouts](/en/docs/errors#timeouts). ## 429 errors [#429-errors] See [Rate limits](/en/docs/rate-limits). Retry after `retry-after`, and run fewer requests at once. ## The model does not see my image or file [#the-model-does-not-see-my-image-or-file] The model reads text only. Put a document's text in the message; images and audio are not understood. ## A follow-up question loses the context [#a-follow-up-question-loses-the-context] Raon keeps no conversation on the server. Send the earlier messages and the model's earlier answers with every request. Ordinary text conversations do not need the earlier reasoning text. When replaying Responses output items, preserve reasoning items in order with their associated items; see the [API reference](/en/docs/api-reference). ## A coding agent does not start or uses the wrong model [#a-coding-agent-does-not-start-or-uses-the-wrong-model] Run the agent's installer again; it tests the key and rewrites its settings. Each agent's page has the manual setup. For Claude Code and Codex, start them with `raon-claude` and `raon-codex`; plain `claude` and `codex` keep your own setup. --- # Hermes > Register Raon as a Hermes provider and choose whether to make it the default. The installer registers Raon as the Hermes provider `custom:raon` and asks whether to make it the default model. Accept to switch to Raon, or decline to keep your current default. Other providers stay as they are, and `hermes model` switches back to one of them. Press Enter at the default-model prompt to accept. `--yes` (`-Yes` on Windows) also accepts the switch. Without a terminal or that option, the installer only registers Raon and keeps the current default. ## Install [#install] ```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 ``` The installer installs Hermes if it is missing, asks for your API key and makes a test call. Hermes reads the key from `~/.raon/hermes.key`, a file only you can read. ## Start [#start] ```bash hermes hermes -z "Explain this repository" hermes model # switch providers ``` ## Set up by hand [#set-up-by-hand] Add your key to Hermes' `.env` (`~/.hermes/.env`, or `%LOCALAPPDATA%\hermes\.env` on Windows) and register the provider: ```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 ``` ## Uninstall [#uninstall] Remove the Raon provider and saved key added by the installer. Hermes itself, other providers, and tool settings remain installed. If setup switched the default model to Raon, removal restores the previous selection unless you have changed it since setup. ```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 ``` A provider or key that existed under the same Raon name before setup is restored when removal can proceed. If you edited the Raon provider, or the default provider still uses Raon after any restoration, removal keeps its provider and key and explains why. This also covers selecting Raon after a registration-only install. A key changed after setup is also kept. Removal uses the installer's journal. Manual setups and older installations without that journal are left unchanged. No API key or API connection is needed, but the agent must still be installed to edit its configuration. Removing a locally saved key does not revoke the key on the server. --- # Getting started > Get an API key and make your first request to Raon. Raon serves the `raon-1-mini-preview` model through three widely used API formats. Connect supported text generation features through the OpenAI and Anthropic SDKs or compatible coding agents using Raon's base URL, API key and model ID. Check the [supported features and limits](/en/docs/limits) when switching from another provider. The model price is zero during this preview. Token usage and rate limits still apply. ## Base URL [#base-url] Every request goes to: ```txt title="Base URL" https://raon-api.krafton.ai ``` ## API key [#api-key] Create a key on the [API keys](https://raon-console.krafton.ai/api-keys) page of the console. Keep it in an environment variable rather than in code: ```bash tab="macOS / Linux" export RAON_API_KEY="" ``` ```powershell tab="Windows (PowerShell)" $env:RAON_API_KEY = "" ``` Send the key as `Authorization: Bearer `. The Messages API also takes it as `x-api-key`, which is what the Anthropic SDKs send. ## First request [#first-request] ```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); ``` The curl examples are written for a macOS or Linux shell. On Windows, run them in WSL or Git Bash, or use the Python or TypeScript examples. ## APIs [#apis] Use the API your client already speaks. A request is not translated between them. [SDKs and frameworks](/en/docs/sdks) shows how to point each client at Raon. | Endpoint | API format | Used by | | --- | --- | --- | | [`POST /v1/chat/completions`](/en/docs/chat-completions) | OpenAI Chat Completions | OpenClaw, Hermes, [other compatible tools](/en/docs/compatible-tools) | | [`POST /v1/responses`](/en/docs/responses) | OpenAI Responses | Codex | | [`POST /v1/messages`](/en/docs/messages) | Anthropic Messages | Claude Code | `GET /v1/models` lists the models your key can call, with their context window and price: ```bash curl https://raon-api.krafton.ai/v1/models \ -H "Authorization: Bearer $RAON_API_KEY" ``` ## Give these docs to an AI agent [#give-these-docs-to-an-ai-agent] This site also publishes the docs for AI agents, in the [llms.txt](https://llmstxt.org) format. When you ask a coding agent to build on Raon, tell it to read `llms.txt` first: ```txt title="Example prompt" Read https://raon-mini.krafton.ai/llms.txt and the pages it links to, then add Raon to this app with the Chat Completions API. ``` | Address | Contents | | --- | --- | | [`/llms.txt`](/llms.txt) | The index: every page as a Markdown link. [`/ko/llms.txt`](/ko/llms.txt) is the Korean one. | | [`/llms-full.txt`](/llms-full.txt) | Every page in one file. | | [`/openapi.yaml`](/openapi.yaml) | The API contract: every endpoint, parameter, refusal and error shape. | Every page is also Markdown at its own address plus `.md`, and the **Copy Markdown** button at the top of each page copies it for pasting into a chat. ## Next steps [#next-steps] --- # Installer options > Run the installers without questions, and undo what they did. The key can also come from `RAON_API_KEY`. To skip the questions, pass options after `bash -s --`, or on Windows run the script as a script block: ```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) | Description | | --- | --- | --- | | `--api-key` | `-ApiKey` | API key | | `--model` | `-Model` | Model ID | | `--base-url` | `-BaseUrl` | API base URL | | `--yes` | `-Yes` | Accept the defaults without asking | | `--uninstall` | `-Uninstall` | Remove what the installer added | | `--help` | `-Help` | Show help | Read a script before you pipe it into a shell, or follow the manual steps on each agent's page instead. ## Uninstall [#uninstall] `--uninstall` removes the command and the files the installer wrote. If an earlier installer had changed `~/.claude/settings.json` or `~/.codex/config.toml`, it also puts your own values back, after copying the file next to the original as `.bak--