CLOVA Studio API

What the CLOVA Studio API is and when to use it

CLOVA Studio is NAVER Cloud Platform’s developer platform for HyperCLOVA X. It combines a browser-based playground with REST APIs that applications can call to generate text, process text and images, stream responses, invoke application-defined functions, return structured JSON, create embeddings, tune models, and use selected retrieval-augmented generation and routing tools.

Use the API when your application needs an AI-powered feature such as Korean-language generation, summarization, classification, question answering, document workflows, image-aware prompts, or tool-assisted application logic. It is not a separate consumer chat application, and the platform does not provide a separately documented first-party persistent assistants runtime equivalent.

For a new integration, the recommended native interface is Chat Completions v3 at POST /v3/chat-completions/{modelName}. This is the better choice when you need CLOVA Studio features such as native multimodal input, function calling, structured outputs, or thinking controls. The OpenAI-compatible endpoint is useful when an existing application or framework already expects the OpenAI client interface.

Getting access and obtaining API keys

Start by subscribing to CLOVA Studio through the NAVER Cloud Platform console. In the CLOVA Studio API Key menu, issue either a test API key for development or a service API key for a registered service application. Keep the key on the server side, preferably in an environment variable or secret manager; do not place it in browser code or commit it to source control.

Requests authenticate with a bearer token. The documented service region is Korea, and CLOVA Studio is available in NAVER Cloud Platform Classic and VPC environments. Account, region, service-app review, and model availability requirements should be checked before production deployment.

export CLOVA_STUDIO_API_KEY="your-key-here"

Choosing the API and model

There are two current integration styles:

Model behavior and limits vary by model. The research identifies HCX-005 in current request examples and documents structured outputs for HCX-007. Do not assume that every model supports every tool, image request, or output feature; check the model-specific API documentation before selecting one.

Making a first native request

The current primary API host is https://clovastudio.stream.ntruss.com/. The following request uses Chat Completions v3 and keeps the native camelCase field names consistent.

curl --fail-with-body --silent --show-error 
  --request POST "https://clovastudio.stream.ntruss.com/v3/chat-completions/HCX-005" 
  --header "Authorization: Bearer ${CLOVA_STUDIO_API_KEY}" 
  --header "Content-Type: application/json" 
  --header "Accept: application/json" 
  --header "X-NCP-CLOVASTUDIO-REQUEST-ID: $(uuidgen 2>/dev/null || date +%s)" 
  --data '{
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain what an API is in two sentences."}
    ],
    "topP": 0.8,
    "topK": 0,
    "maxCompletionTokens": 256,
    "temperature": 0.3
  }'

The messages array supplies the conversation. A system message sets general behavior, while a user message contains the task. Generation controls such as temperature, top-p, and the completion-token limit influence output style and length. Keep the request ID header in production so requests can be traced during troubleshooting.

Understanding the response

A successful native response contains a result object with the generated message. Error responses and status information can use status fields, while HTTP status codes communicate request-level failures. Your application should check both the HTTP status and the returned body rather than assuming that every response contains generated text.

For the OpenAI-compatible endpoint, generated content is normally read from choices[0].message.content. A tool request instead returns tool-call information that your application must validate and execute. Never execute model-produced arguments without applying your own schema validation, authorization, and business rules.

How pricing works

CLOVA Studio uses usage-based billing. The amount depends on the model, purpose, and number of tokens processed or generated. The consulted public API documentation does not provide one stable universal price table, so current model-specific prices should be checked in the NAVER Cloud Platform portal under the relevant CLOVA Studio service.

For budgeting, measure prompt and completion tokens in representative workloads, account for retries and streaming requests, and separate development traffic from production traffic. Do not treat the example QPM and TPM limits as prices or guaranteed capacity.

Important capabilities for developers

Streaming responses

Streaming sends output progressively instead of waiting for the entire completion. It is useful for chat interfaces and long responses because the user can see partial output sooner. Native streaming uses an event-stream response and the Accept: text/event-stream header. The OpenAI-compatible interface uses the familiar stream: true request field.

Text and image input

Chat Completions v3 supports text-and-image input, subject to model and per-message restrictions. Image input is sent as part of the chat request rather than through a general-purpose persistent file API. Native function calling cannot be combined with image interpretation or inference in the same request.

Function and tool calling

Function calling lets the model propose a call to a function that your application defines, such as looking up an order or retrieving weather data. CLOVA Studio returns the function name and arguments; your server performs the actual operation and can then send the result back to the model. The platform supports function calling through Chat Completions v3 and the OpenAI-compatible API, but function calling and structured outputs cannot be combined in the same native request.

Structured outputs

Structured outputs are designed for responses that must follow a defined JSON structure rather than free-form prose. Current documentation identifies this feature for HCX-007. Confirm the supported schema format and model restrictions in the current reference, and still validate the returned data in application code. A structured response is not a replacement for authorization or input validation.

Embeddings, tuning and retrieval workflows

The platform includes embedding APIs, dataset-backed tuning, reranking, RAG-related tools, router capabilities, and skill trainer workflows. Tuning datasets are handled through NAVER Cloud Object Storage. These features are separate from ordinary chat completion requests and may have their own access, model, dataset, and review requirements.

Using the OpenAI-compatible API

The OpenAI-compatible base URL is https://clovastudio.stream.ntruss.com/v1/openai. The example below uses the current OpenAI Python client syntax while pointing it at CLOVA Studio.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CLOVA_STUDIO_API_KEY"],
    base_url="https://clovastudio.stream.ntruss.com/v1/openai"
)

response = client.chat.completions.create(
    model="HCX-005",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain REST APIs in three bullet points."}
    ],
    temperature=0.3,
    max_completion_tokens=256
)

print(response.choices[0].message.content)

The compatible endpoint uses snake_case names such as max_completion_tokens. Do not copy native fields such as maxCompletionTokens into this request format.

Adding a function tool

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
        }
    }
}]

response = client.chat.completions.create(
    model="HCX-005",
    messages=[{"role": "user", "content": "What is the weather in Seoul?"}],
    tools=tools,
    tool_choice="auto",
    max_completion_tokens=1024
)

message = response.choices[0].message
if message.tool_calls:
    call = message.tool_calls[0]
    print(call.function.name, call.function.arguments)

This code only displays the proposed call. A production application must parse and validate the arguments, check whether the user is allowed to perform the operation, execute the function, and handle failures before optionally continuing the conversation.

Playground, SDKs and developer tooling

CLOVA Studio includes a web playground for experimenting with prompts and supported workflows before writing application code. The platform provides detailed REST documentation and an OpenAI-compatible interface. The consulted documentation does not identify a provider-specific official Python, JavaScript, or PHP SDK.

Python and JavaScript applications can use the official OpenAI client libraries through the compatible base URL. PHP applications and other languages can call the REST endpoint with standard HTTPS tooling. Keep the package version and client syntax current, and follow the endpoint’s documented parameter naming rather than mixing native and compatible request formats.

Limits and production considerations

Usage controls are expressed through QPM, or queries per minute, and TPM, or tokens per minute. Limits vary by model, tool, account, and purpose. Response headers expose request and token limits, remaining capacity, and reset information, including headers such as x-ratelimit-limit-requests and x-ratelimit-limit-tokens.

The service documentation gives examples of 60 QPM and 60,000 TPM for HCX-007 and HCX-005 in web/test usage, but these values can change and do not guarantee throughput. Read the returned headers, apply bounded exponential backoff for transient failures, and design for HTTP 401, 403, 408, 413, 429, and 5xx responses.

There is no universal public latency figure or fixed latency SLA in the consulted API documentation. Delays can vary with infrastructure load and traffic. Dedicated guaranteed-usage arrangements may be available through customer support, but should be confirmed for the specific account.

Before production use, move from a test key to a service key where required, complete service-app review requirements, protect credentials, set usage monitoring, validate model outputs, and review the current NAVER Cloud Platform terms and privacy documentation. The public API documentation does not establish one universal retention period or one provider-wide training-use policy for every CLOVA Studio deployment.

When CLOVA Studio is a good or poor choice

CLOVA Studio is a good choice when you need access to HyperCLOVA X through NAVER Cloud Platform, want a native API with Korean-region availability, need text-and-image input or tool features, or are migrating an application that already uses the OpenAI client interface. Its playground, REST documentation, streaming, structured-output support, tuning workflows, and usage headers are useful during development and operations.

It may be a poor fit when you require a globally uniform endpoint and pricing model, a provider-specific SDK for your language, a general-purpose persistent assistant runtime, a universal file-storage API, guaranteed public latency figures, or a single retention and training policy that applies identically to every deployment. The Korean service region, account prerequisites, model-specific restrictions, service-app review, and changing usage limits should be evaluated before committing to the platform.