Claude 네이티브 형식
curl --request POST \
--url https://api.gravitex.ai/v1/messages \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"messages": [
{}
],
"max_tokens": 123,
"system": {},
"temperature": 123,
"top_p": 123,
"top_k": 123,
"stream": true,
"stop_sequences": [
{}
],
"tools": [
{}
],
"tool_choice": {},
"thinking": {},
"output_config": {},
"metadata": {},
"mcp_servers": [
{}
],
"context_management": {},
"cache_control": {}
}
'import requests
url = "https://api.gravitex.ai/v1/messages"
payload = {
"model": "<string>",
"messages": [{}],
"max_tokens": 123,
"system": {},
"temperature": 123,
"top_p": 123,
"top_k": 123,
"stream": True,
"stop_sequences": [{}],
"tools": [{}],
"tool_choice": {},
"thinking": {},
"output_config": {},
"metadata": {},
"mcp_servers": [{}],
"context_management": {},
"cache_control": {}
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
messages: [{}],
max_tokens: 123,
system: {},
temperature: 123,
top_p: 123,
top_k: 123,
stream: true,
stop_sequences: [{}],
tools: [{}],
tool_choice: {},
thinking: {},
output_config: {},
metadata: {},
mcp_servers: [{}],
context_management: {},
cache_control: {}
})
};
fetch('https://api.gravitex.ai/v1/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gravitex.ai/v1/messages",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'messages' => [
[
]
],
'max_tokens' => 123,
'system' => [
],
'temperature' => 123,
'top_p' => 123,
'top_k' => 123,
'stream' => true,
'stop_sequences' => [
[
]
],
'tools' => [
[
]
],
'tool_choice' => [
],
'thinking' => [
],
'output_config' => [
],
'metadata' => [
],
'mcp_servers' => [
[
]
],
'context_management' => [
],
'cache_control' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gravitex.ai/v1/messages"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"max_tokens\": 123,\n \"system\": {},\n \"temperature\": 123,\n \"top_p\": 123,\n \"top_k\": 123,\n \"stream\": true,\n \"stop_sequences\": [\n {}\n ],\n \"tools\": [\n {}\n ],\n \"tool_choice\": {},\n \"thinking\": {},\n \"output_config\": {},\n \"metadata\": {},\n \"mcp_servers\": [\n {}\n ],\n \"context_management\": {},\n \"cache_control\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gravitex.ai/v1/messages")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"max_tokens\": 123,\n \"system\": {},\n \"temperature\": 123,\n \"top_p\": 123,\n \"top_k\": 123,\n \"stream\": true,\n \"stop_sequences\": [\n {}\n ],\n \"tools\": [\n {}\n ],\n \"tool_choice\": {},\n \"thinking\": {},\n \"output_config\": {},\n \"metadata\": {},\n \"mcp_servers\": [\n {}\n ],\n \"context_management\": {},\n \"cache_control\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gravitex.ai/v1/messages")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"max_tokens\": 123,\n \"system\": {},\n \"temperature\": 123,\n \"top_p\": 123,\n \"top_k\": 123,\n \"stream\": true,\n \"stop_sequences\": [\n {}\n ],\n \"tools\": [\n {}\n ],\n \"tool_choice\": {},\n \"thinking\": {},\n \"output_config\": {},\n \"metadata\": {},\n \"mcp_servers\": [\n {}\n ],\n \"context_management\": {},\n \"cache_control\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "msg_xxx",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Artificial intelligence is a branch of computer science that focuses on creating intelligent machines capable of performing tasks that typically require human intelligence..."
}
],
"model": "claude-sonnet-4-5-20250929",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 25,
"output_tokens": 100
}
}
대화 및 텍스트
Claude 네이티브 형식
Claude 네이티브 메시지 API
POST
/
v1
/
messages
Claude 네이티브 형식
curl --request POST \
--url https://api.gravitex.ai/v1/messages \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"messages": [
{}
],
"max_tokens": 123,
"system": {},
"temperature": 123,
"top_p": 123,
"top_k": 123,
"stream": true,
"stop_sequences": [
{}
],
"tools": [
{}
],
"tool_choice": {},
"thinking": {},
"output_config": {},
"metadata": {},
"mcp_servers": [
{}
],
"context_management": {},
"cache_control": {}
}
'import requests
url = "https://api.gravitex.ai/v1/messages"
payload = {
"model": "<string>",
"messages": [{}],
"max_tokens": 123,
"system": {},
"temperature": 123,
"top_p": 123,
"top_k": 123,
"stream": True,
"stop_sequences": [{}],
"tools": [{}],
"tool_choice": {},
"thinking": {},
"output_config": {},
"metadata": {},
"mcp_servers": [{}],
"context_management": {},
"cache_control": {}
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
messages: [{}],
max_tokens: 123,
system: {},
temperature: 123,
top_p: 123,
top_k: 123,
stream: true,
stop_sequences: [{}],
tools: [{}],
tool_choice: {},
thinking: {},
output_config: {},
metadata: {},
mcp_servers: [{}],
context_management: {},
cache_control: {}
})
};
fetch('https://api.gravitex.ai/v1/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gravitex.ai/v1/messages",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'messages' => [
[
]
],
'max_tokens' => 123,
'system' => [
],
'temperature' => 123,
'top_p' => 123,
'top_k' => 123,
'stream' => true,
'stop_sequences' => [
[
]
],
'tools' => [
[
]
],
'tool_choice' => [
],
'thinking' => [
],
'output_config' => [
],
'metadata' => [
],
'mcp_servers' => [
[
]
],
'context_management' => [
],
'cache_control' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gravitex.ai/v1/messages"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"max_tokens\": 123,\n \"system\": {},\n \"temperature\": 123,\n \"top_p\": 123,\n \"top_k\": 123,\n \"stream\": true,\n \"stop_sequences\": [\n {}\n ],\n \"tools\": [\n {}\n ],\n \"tool_choice\": {},\n \"thinking\": {},\n \"output_config\": {},\n \"metadata\": {},\n \"mcp_servers\": [\n {}\n ],\n \"context_management\": {},\n \"cache_control\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gravitex.ai/v1/messages")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"max_tokens\": 123,\n \"system\": {},\n \"temperature\": 123,\n \"top_p\": 123,\n \"top_k\": 123,\n \"stream\": true,\n \"stop_sequences\": [\n {}\n ],\n \"tools\": [\n {}\n ],\n \"tool_choice\": {},\n \"thinking\": {},\n \"output_config\": {},\n \"metadata\": {},\n \"mcp_servers\": [\n {}\n ],\n \"context_management\": {},\n \"cache_control\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gravitex.ai/v1/messages")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"max_tokens\": 123,\n \"system\": {},\n \"temperature\": 123,\n \"top_p\": 123,\n \"top_k\": 123,\n \"stream\": true,\n \"stop_sequences\": [\n {}\n ],\n \"tools\": [\n {}\n ],\n \"tool_choice\": {},\n \"thinking\": {},\n \"output_config\": {},\n \"metadata\": {},\n \"mcp_servers\": [\n {}\n ],\n \"context_management\": {},\n \"cache_control\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "msg_xxx",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Artificial intelligence is a branch of computer science that focuses on creating intelligent machines capable of performing tasks that typically require human intelligence..."
}
],
"model": "claude-sonnet-4-5-20250929",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 25,
"output_tokens": 100
}
}
소개
Claude의 네이티브 메시지 API로, Claude Code와 같은 Anthropic 네이티브 클라이언트에 적합합니다. 이 API는 Anthropic 사양을 따르며 Extended Thinking, 도구 호출 등 Claude 모델의 전체 기능을 제공합니다.OpenAI 호환 클라이언트(예: OpenAI SDK)를 사용하는 경우
/v1/chat/completions 엔드포인트 사용을 권장합니다.인증
string
필수
Bearer 토큰, 예:
Bearer sk-xxxxxxxxxx요청 매개변수
string
필수
Claude 모델 식별자. 지원 모델:
claude-fable-5- Claude Fable 5 (최신, 최고 성능)claude-opus-5- Claude Opus 5 (최신, 복잡한 에이전트 및 코딩 작업)claude-sonnet-5- Claude Sonnet 5 (속도와 지능의 균형)claude-opus-4-8- Claude Opus 4.8claude-opus-4-7- Claude Opus 4.7claude-opus-4-6- Claude Opus 4.6claude-sonnet-4-6- Claude Sonnet 4.6 (균형 잡힌 성능)claude-opus-4-5-20251101- Claude Opus 4.5claude-haiku-4-5-20251001- Claude Haiku 4.5 (가장 빠름)claude-sonnet-4-5-20250929- Claude Sonnet 4.5claude-sonnet-4-20250514- Claude Sonnet 4- 기타 Claude 시리즈 모델
array
필수
대화 메시지 목록. 각 항목은
role(user/assistant)과 content를 포함합니다. content는 문자열 또는 미디어 콘텐츠 배열일 수 있습니다.number
필수
생성할 최대 토큰 수. 0보다 커야 합니다.
string|array
시스템 프롬프트. 문자열 또는 미디어 콘텐츠 배열로 지정할 수 있습니다. 모델의 동작과 역할을 설정하는 데 사용됩니다.
number
기본값:"1.0"
무작위성 제어, 0-1. 값이 높을수록 응답이 더 무작위적입니다. 확장 사고 사용 시 1.0으로 설정하는 것을 권장합니다.
number
기본값:"1.0"
Nucleus 샘플링 매개변수, 0-1. 생성 다양성을 제어합니다. 확장 사고 사용 시 0으로 설정하는 것을 권장합니다.
number
Top-K 샘플링 매개변수. 일부 모델에서만 지원됩니다.
boolean
기본값:"false"
스트리밍 출력 활성화 여부. SSE 형식의 데이터 청크를 반환합니다. 확장 사고 사용 시 활성화를 권장합니다.
array
중지 시퀀스 목록. 모델이 이 시퀀스를 생성하면 생성이 중단됩니다.
array
도구 정의 목록. 함수 도구와 웹 검색 도구를 지원합니다.
object
도구 선택 전략. 모델이 도구를 사용하는 방식을 제어합니다.
object
확장 사고 설정. Claude의 심층 추론 기능을 활성화합니다.
| 하위 필드 | 유형 | 설명 |
|---|---|---|
type | enum | "adaptive": 적응형 사고. 모델이 언제, 얼마나 깊이 사고할지 스스로 결정합니다. "disabled": 사고 비활성화. Claude 4.5 이하 모델은 "enabled"와 budget_tokens를 함께 사용합니다 |
display | enum | "summarized": 사고 과정의 요약을 반환합니다. "omitted": 사고 내용을 반환하지 않습니다. 사고 자체는 그대로 수행되며 비용도 동일하고, omitted는 표시만 하지 않을 뿐입니다(스트리밍 시 본문 응답이 더 빨리 시작되는 장점이 있습니다). type: "disabled"와 함께 사용할 수 없습니다 |
budget_tokens | number | type: "enabled"(Claude 4.5 이하 모델)와 함께 사용할 때만 유효합니다. 최소 1024이며 max_tokens보다 작아야 합니다. Claude 4.7 이상 모델은 이 방식을 지원하지 않습니다 |
{"type": "adaptive"} // 적응형 사고
{"type": "adaptive", "display": "summarized"} // 적응형 사고 + 사고 요약 반환
{"type": "disabled"} // 사고 비활성화
display의 기본값은 모델마다 다릅니다: Claude Fable 5, Opus 5, Sonnet 5, Opus 4.8, Opus 4.7은 "omitted"가 기본값이며, Claude Opus 4.6, Sonnet 4.6 및 이전 모델은 "summarized"가 기본값입니다. 전자에서 사고 과정을 사용자에게 보여주려면 반드시 "display": "summarized"를 명시적으로 설정해야 하며, 그렇지 않으면 사고 내용이 비어 있습니다.object
출력 설정. 모델의 사고 깊이와 토큰 소비를 제어합니다.
이 매개변수는 응답의 모든 토큰(본문, 도구 호출, 사고)에 영향을 주므로 사고를 활성화하지 않아도 적용됩니다.지원 단계는 모델마다 다릅니다:
| 하위 필드 | 유형 | 설명 |
|---|---|---|
effort | enum | 사고 깊이. "low" / "medium" / "high" / "xhigh" / "max" 중 선택하며 기본값은 "high"입니다. 단계가 높을수록 대체로 더 정확하고 깊이 있는 답변을 얻지만 소요 시간과 토큰 소비도 늘어납니다. 코딩이나 에이전트 작업에는 "xhigh" 또는 "max"를 시도해 보세요 |
{"effort": "high"} // 기본 단계, 매개변수를 생략한 것과 동일
{"effort": "xhigh"} // 코딩 / 에이전트 등 장기 작업
"xhigh"는 Claude Fable 5, Opus 5, Opus 4.8, Opus 4.7, Sonnet 5에서만 지원되며, Claude Sonnet 4.5 및 이전 모델은 이 매개변수 자체를 지원하지 않습니다.Claude Opus 5에서는
effort가 "xhigh" 또는 "max"일 때 사고를 비활성화할 수 없습니다. 해당 단계에서 "thinking": {"type": "disabled"}를 함께 전달하면 400 오류가 반환됩니다. 사고를 끄려면 effort를 "high" 이하로 설정하세요.object
추적 및 디버깅용 요청 메타데이터.
array
MCP(Model Context Protocol) 서버 설정.
object
컨텍스트 관리 설정. 대화 컨텍스트 처리 방식을 제어합니다.
object
자동 캐싱을 활성화합니다. 요청 본문 최상위에 지정하면 시스템이 마지막 캐시 가능 블록에 브레이크포인트를 자동으로 적용하고, 대화가 길어짐에 따라 자동으로 뒤로 이동시킵니다. 별도의 표시를 관리할 필요가 없습니다. 프롬프트 캐싱 참조.
{"type": "ephemeral"} // 5분 캐시(기본값)
{"type": "ephemeral", "ttl": "1h"} // 1시간 캐시
레거시 Amazon Bedrock 통합(
InvokeModel / Converse, Opus 4.6 이하 모델)은 최상위 cache_control을 지원하지 않으며 400을 반환합니다. 해당 모델에서는 블록 단위의 명시적 브레이크포인트를 사용하세요. 플랫폼별 지원 현황 참조.프롬프트 캐싱
프롬프트 캐싱을 사용하면 자주 사용하는 컨텍스트 콘텐츠를 캐시하여 비용을 크게 절감하고 응답 속도를 향상시킬 수 있습니다. 활성화 방법은 두 가지이며, 단독으로도 조합해서도 사용할 수 있습니다.| 방식 | 지정 위치 | 사용 시점 |
|---|---|---|
| 자동 캐싱 | cache_control을 요청 본문 최상위에 지정 | 멀티턴 대화. 브레이크포인트가 마지막 캐시 가능 블록에 자동으로 잡히고 대화에 따라 이동하므로 관리가 필요 없음 |
| 명시적 브레이크포인트 | cache_control을 system / messages의 콘텐츠 블록에 지정 | 캐시 경계를 정밀하게 제어할 때. 예: 시스템 프롬프트만 캐시하거나 특정 장문 문서만 캐시 |
캐시 제어 매개변수
두 방식의 필드 구조는 동일합니다. 필드 설명:| 필드 | 설명 |
|---|---|
type | 캐시 유형. 항상 "ephemeral" |
ttl | 캐시 유효 기간(선택). 생략하면 5분 캐시(기본값, 가장 비용 효율적), "1h"로 지정하면 1시간 캐시(장기적으로 안정적인 컨텍스트에 적합하지만 쓰기 비용이 더 높음) |
{"type": "ephemeral"} // 5분 캐시(기본값)
{"type": "ephemeral", "ttl": "1h"} // 1시간 캐시
자동 캐싱(최상위 cache_control)
cache_control을 요청 본문 루트에 그대로 넣으면 됩니다. 콘텐츠 블록에 별도 표시를 할 필요가 없습니다.
{
"model": "claude-opus-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": "당신은 도움이 되는 어시스턴트입니다.",
"messages": [
{"role": "user", "content": "제 이름은 Alex이고 머신러닝을 합니다."},
{"role": "assistant", "content": "반갑습니다, Alex!"},
{"role": "user", "content": "제가 무슨 일을 한다고 했죠?"}
]
}
| 요청 | 콘텐츠(◀ 가 브레이크포인트) | 캐시 동작 |
|---|---|---|
| 1회 | System + User(1) + Asst(1) + User(2) ◀ | 전체가 캐시에 기록됨 |
| 2회 | System + … + User(2) + Asst(2) + User(3) ◀ | System~User(2) 캐시 적중, Asst(2) + User(3) 기록 |
| 3회 | System + … + User(3) + Asst(3) + User(4) ◀ | System~User(3) 캐시 적중, Asst(3) + User(4) 기록 |
플랫폼별 지원 현황
자동 캐싱(최상위cache_control)은 레거시 Amazon Bedrock 통합을 제외한 모든 플랫폼에서 사용할 수 있습니다.
| 플랫폼 | 최상위 cache_control |
|---|---|
| Anthropic 공식 API | ✅ |
| Claude Platform on AWS(Anthropic 운영, AWS Marketplace 과금) | ✅ |
| Claude in Amazon Bedrock(Messages API 엔드포인트, Opus 4.7 이상) | ✅ |
레거시 Claude on Amazon Bedrock(InvokeModel / Converse, Opus 4.6 이하) | ❌ 400 반환 |
| Google Vertex AI | ✅ |
| Microsoft Foundry | ✅ |
| 모델 | 최상위 cache_control | 설명 |
|---|---|---|
| Fable 5, Opus 5, Opus 4.8, Opus 4.7, Sonnet 5 | ✅ | Messages API 엔드포인트로 제공되며 모델 ID는 anthropic.claude-opus-5 형태(ARN 버전 없음) |
| Opus 4.6, Sonnet 4.6, Opus 4.5, Sonnet 4.5, Sonnet 4 | ❌ | 레거시 InvokeModel / Converse로 제공되며 모델 ID에 ARN 버전이 포함됨. 명시적 브레이크포인트 사용 |
특정 모델이 실제로 어떤 경로를 사용하는지 확실하지 않다면 동일한 프리픽스로 두 번 요청한 뒤 두 번째 응답의
usage.cache_read_input_tokens가 0보다 큰지 확인하세요.명시적 브레이크포인트(블록 단위 cache_control)
system 배열 요소 또는 messages의 content 배열 요소 내부에 지정합니다.
{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "길고 안정적인 컨텍스트...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "캐시할 긴 문서...",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}
]
}
]
}
두 방식 조합하기
자동 캐싱과 명시적 브레이크포인트는 함께 사용할 수 있습니다. 대표적인 패턴은 명시적 브레이크포인트로 시스템 프롬프트를 고정하고, 길어지는 대화 부분은 자동 캐싱에 맡기는 것입니다.{
"model": "claude-opus-5",
"max_tokens": 1024,
"cache_control": {"type": "ephemeral"},
"system": [
{
"type": "text",
"text": "길고 안정적인 시스템 프롬프트...",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "핵심 조항은 무엇인가요?"}
]
}
- 자동 캐싱은 4개의 브레이크포인트 슬롯 중 1개를 사용합니다
- 명시적 브레이크포인트가 이미 4개인 상태에서 최상위
cache_control을 보내면 400을 반환합니다(남은 슬롯 없음) - 마지막 블록에 **동일한
ttl**의 명시적cache_control이 이미 있으면 자동 캐싱은 무동작이며 슬롯을 추가로 쓰지 않습니다 - 마지막 블록에 **다른
ttl**의 명시적cache_control이 있으면 400을 반환합니다 - 마지막 블록이 브레이크포인트 대상으로 적합하지 않으면 시스템이 앞쪽으로 되짚어 가장 가까운 적합한 블록을 찾고, 없으면 캐싱을 건너뜁니다(오류 없음)
캐싱 메커니즘
- 캐시 브레이크포인트: 요청당 최대 4개의 콘텐츠 블록을 지정할 수 있습니다. 각 브레이크포인트는 처음부터 해당 블록까지의 전체 프리픽스를 캐시 항목으로 각각 기록합니다
- 캐시 적중: 브레이크포인트 지점에서 프리픽스를 비교하며, 일치하지 않으면 한 블록씩 앞으로 되짚어 탐색합니다. 되짚기 범위는 최대 20개 블록이며, 이 범위를 벗어난 캐시는 적중하지 않으므로 더 앞쪽에 브레이크포인트를 추가하는 것이 좋습니다
- 캐시 임계값: 모델별 최소 캐시 가능 길이보다 짧은 콘텐츠는 캐시되지 않습니다(오류 없이 일반 입력으로 처리됨). 아래 표 참조
- 캐시 유효 기간: 5분(기본값) 또는 1시간
- 비용: 캐시 읽기는 일반 입력 가격의 10%(90% 저렴)이며, 캐시 쓰기에는 할증이 있습니다 — 5분 캐시는 1.25배, 1시간 캐시는 2배
모델별 최소 캐시 가능 길이
| 모델 | 최소 캐시 가능 길이 |
|---|---|
| Claude Fable 5, Claude Opus 5 | 512 토큰 |
| Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 | 1,024 토큰 |
| Claude Opus 4.7 | 2,048 토큰 |
| Claude Opus 4.6, Claude Opus 4.5, Claude Haiku 4.5 | 4,096 토큰 |
사용 사례
- 긴 문서 분석:
system에 대용량 문서를 캐시하고 여러 질문 수행 - 코드베이스 이해: 코드 컨텍스트를 캐시하여 다중 턴 코드 분석
- 지식 베이스 Q&A: 지식 베이스 콘텐츠를 캐시하여 빠른 조회
- 다중 턴 대화: 대화 기록을 캐시하여 컨텍스트 일관성 유지
기본 예제
- 비스트리밍 요청
- 스트리밍 요청 (SSE)
- Python 예제 (Anthropic SDK)
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Please briefly introduce artificial intelligence"}
]
}'
curl -N -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"stream": true,
"messages": [
{"role": "user", "content": "Please briefly introduce artificial intelligence"}
]
}'
from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai"
)
# Non-streaming
message = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[
{"role": "user", "content": "Please briefly introduce artificial intelligence"}
]
)
print(message.content[0].text)
# Streaming
with client.messages.stream(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
messages=[
{"role": "user", "content": "Please briefly introduce artificial intelligence"}
]
) as stream:
for text_block in stream.text_stream:
print(text_block, end="")
{
"id": "msg_xxx",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Artificial intelligence is a branch of computer science that focuses on creating intelligent machines capable of performing tasks that typically require human intelligence..."
}
],
"model": "claude-sonnet-4-5-20250929",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 25,
"output_tokens": 100
}
}
고급 기능
시스템 프롬프트
시스템 프롬프트는 문자열 또는 미디어 콘텐츠 배열로 설정할 수 있습니다:- 문자열 형식
- 배열 형식
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"system": "You are a helpful assistant that excels at answering questions.",
"messages": [
{"role": "user", "content": "What is machine learning?"}
]
}'
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"system": [
{"type": "text", "text": "You are a helpful assistant that excels at answering questions."}
],
"messages": [
{"role": "user", "content": "What is machine learning?"}
]
}'
확장 사고
Claude는 확장 사고를 지원하여 모델이 심층 추론을 수행할 수 있습니다. 활성화하면 모델이 최종 답변을 생성하기 전에 내부적으로 사고합니다.- 기본 사용법
- Python 예제
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 4096,
"temperature": 1.0,
"top_p": 0,
"stream": true,
"messages": [
{"role": "user", "content": "Give a medium difficulty geometry problem and solve it step by step"}
]
}'
from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai"
)
with client.messages.stream(
model="claude-sonnet-4-5-20250929",
max_tokens=4096,
thinking={
"type": "enabled",
"budget_tokens": 4096
},
temperature=1.0,
top_p=0,
messages=[
{"role": "user", "content": "Give a medium difficulty geometry problem and solve it step by step"}
]
) as stream:
for event in stream:
if event.type == "content_block_delta":
if hasattr(event.delta, "thinking"):
# Thinking process
print(f"[Thinking] {event.delta.thinking}", end="")
elif hasattr(event.delta, "text"):
# Final answer
print(event.delta.text, end="")
budget_tokens는 1024보다 커야 합니다- 확장 사고 사용 시
temperature: 1.0,top_p: 0설정을 권장합니다 - 사고 과정을 보려면 스트리밍 출력(
stream: true)을 활성화해야 합니다
도구 호출
함수 도구와 웹 검색 도구를 지원합니다:- 함수 도구
- Claude 공식 웹 검색 도구
- 전체 도구 호출 흐름
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"tools": [
{
"name": "get_weather",
"description": "Get weather information for a city",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name"
}
},
"required": ["city"]
}
}
],
"tool_choice": {
"type": "auto"
},
"messages": [
{"role": "user", "content": "What is the weather in Shanghai?"}
]
}'
Claude는 공식 웹 검색 도구 기본 사용법:검색 횟수 제한:위치 정보 포함 (검색 정확도 향상):Python 예제:
web_search_20250305를 지원하며, 실시간으로 웹을 검색하고 응답에 인용 출처를 포함할 수 있습니다.참고: AWS Bedrock은 이 검색 도구를 지원하지 않습니다
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"tools": [
{
"type": "web_search_20250305",
"name": "web_search"
}
],
"messages": [
{"role": "user", "content": "What are the latest news about artificial intelligence?"}
]
}'
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"tools": [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5
}
],
"messages": [
{"role": "user", "content": "Search for today'\''s weather in Beijing"}
]
}'
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"tools": [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5,
"user_location": {
"type": "approximate",
"timezone": "Asia/Shanghai",
"country": "CN",
"region": "Beijing",
"city": "Beijing"
}
}
],
"messages": [
{"role": "user", "content": "What'\''s the weather in Shanghai today?"}
]
}'
from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai"
)
message = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
tools=[
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5
}
],
messages=[
{"role": "user", "content": "What are the latest news about artificial intelligence?"}
]
)
print(message.content[0].text)
type은"web_search_20250305"여야 합니다name은"web_search"여야 합니다max_uses(선택): 단일 대화에서 최대 검색 횟수, 권장값: 2-10user_location(선택): 검색 결과의 지역화 정확도를 높이는 사용자 위치 정보- 검색 결과는 응답에 인용 출처가 자동으로 포함됩니다
- Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 등 지원 모델 포함
1단계: 모델이 도구 호출 요청 반환2단계: 도구 실행 결과 반환
{
"id": "msg_xxx",
"content": [
{
"type": "tool_use",
"id": "toolu_xxx",
"name": "get_weather",
"input": {"city": "Shanghai"}
}
],
"stop_reason": "tool_use"
}
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"tools": [...],
"messages": [
{"role": "user", "content": "What is the weather in Shanghai?"},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_xxx",
"name": "get_weather",
"input": {"city": "Shanghai"}
}
]
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_xxx",
"content": "{\"temp\":\"22°C\",\"condition\":\"Cloudy\",\"aqi\":53}"
}
]
}
]
}'
tool_choice 매개변수 상세
tool_choice는 모델이 도구를 사용하는 방식을 제어합니다:
| 값 | 설명 |
|---|---|
{"type": "auto"} | 도구 사용 여부를 자동 결정 (기본값) |
{"type": "any"} | 최소 하나의 도구를 반드시 사용 |
{"type": "none"} | 도구를 사용하지 않음 |
{"type": "tool", "name": "tool_name"} | 지정된 도구를 반드시 사용 |
{
"tool_choice": {
"type": "auto",
"disable_parallel_tool_use": false
}
}
멀티모달 입력 (이미지)
메시지에 이미지를 포함할 수 있습니다:curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}
},
{
"type": "text",
"text": "What is in this image?"
}
]
}
]
}'
프롬프트 캐싱
자주 사용하는 컨텍스트 콘텐츠를 캐시하면 비용을 크게 절감하고 응답 속도를 향상시킬 수 있습니다.- 시스템 캐시 (5분)
- 메시지 캐시 (1시간)
- Python SDK 예제
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are a professional technical documentation analyst. Here is the complete AWS Lambda technical documentation:\n\nAWS Lambda is a serverless computing service...[large documentation content, at least 1024 tokens]",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "What is Lambda's pricing model?"}
]
}'
{
"usage": {
"input_tokens": 50,
"cache_creation_input_tokens": 1200,
"cache_read_input_tokens": 0,
"output_tokens": 150
}
}
{
"usage": {
"input_tokens": 45,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 1200,
"output_tokens": 100
}
}
curl -X POST "https://api.gravitex.ai/v1/messages" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxxxxxx" \
-d '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 1024,
"system": "You are a Python programming assistant",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Analyze this code:\n```python\n[large code snippet, at least 1024 tokens]\n```",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}
]
},
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "The main functionality of this code is...[detailed analysis]",
"cache_control": {"type": "ephemeral", "ttl": "1h"}
}
]
},
{
"role": "user",
"content": "How can I optimize the performance of this code?"
}
]
}'
ttl: "1h")의 장점:- 1시간 캐시 유효 기간, 긴 세션에 적합
- 코드 리뷰, 문서 분석 등에 이상적
- 캐시 히트 후 후속 요청이 더 빠름
from anthropic import Anthropic
client = Anthropic(
api_key="sk-xxxxxxxxxx",
base_url="https://api.gravitex.ai"
)
# First request: Create cache
message1 = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are a professional document analyst...[long text content]",
"cache_control": {"type": "ephemeral"}
}
],
messages=[
{"role": "user", "content": "First question"}
]
)
print(f"Cache created: {message1.usage.cache_creation_input_tokens} tokens")
print(f"Cache read: {message1.usage.cache_read_input_tokens} tokens")
# Second request within 5 minutes: Use cache
message2 = client.messages.create(
model="claude-sonnet-4-5-20250929",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are a professional document analyst...[same long text]",
"cache_control": {"type": "ephemeral"}
}
],
messages=[
{"role": "user", "content": "Second question"}
]
)
print(f"Cache created: {message2.usage.cache_creation_input_tokens} tokens")
print(f"Cache read: {message2.usage.cache_read_input_tokens} tokens")
캐시 핵심 사항:
- 캐싱이 적용되려면 콘텐츠가 모델별 최소 캐시 가능 길이 이상이어야 합니다(모델에 따라 512~4,096 토큰, 위 표 참조)
ttl을 생략하면 캐시는 5분간 유효합니다ttl: "1h"로 지정하면 캐시는 1시간 유효합니다- 캐시 읽기 비용은 일반 입력보다 90% 저렴하며, 캐시 쓰기에는 할증이 있습니다(5분 1.25배, 1시간 2배)
- 요청당 최대 4개 블록을 지정할 수 있으며, 각 브레이크포인트가 각각 캐시 항목을 기록합니다
- 캐시는 정확한 콘텐츠 일치를 기반으로 하며, 변경 시 캐시가 무효화됩니다
모범 사례:
- 변경되지 않는 긴 컨텍스트(문서, 코드베이스 등)를
system에 캐싱 활성화와 함께 배치 - 장기적으로 안정적인 콘텐츠에는 1시간 캐시(
ttl: "1h") 사용 - 자주 변경되는 콘텐츠에는 기본 5분 캐시(
ttl생략) 사용 - 다중 턴 대화에서 대화 기록 캐시
cache_creation_input_tokens와cache_read_input_tokens를 모니터링하여 비용 최적화
응답 형식
- 비스트리밍 응답
- 스트리밍 응답
{
"id": "msg_xxx",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Response content..."
}
],
"model": "claude-sonnet-4-5-20250929",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 25,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"output_tokens": 100
}
}
input_tokens: 현재 요청의 비캐시 입력 토큰cache_creation_input_tokens: 최초 캐시된 토큰 (첫 요청에만 존재)cache_read_input_tokens: 캐시에서 읽은 토큰 (캐시 히트 시 존재)output_tokens: 생성된 출력 토큰
스트리밍 응답은 SSE(Server-Sent Events) 형식으로 반환되며, 다음 이벤트 유형을 포함합니다:확장 사고 사용 시
message_start: 메시지 시작content_block_start: 콘텐츠 블록 시작content_block_delta: 콘텐츠 델타 (text또는thinking포함)content_block_stop: 콘텐츠 블록 종료message_delta: 메시지 델타 (usage 정보 포함)message_stop: 메시지 종료
event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-5-20250929","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":25,"output_tokens":0}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Response"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" content"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":100}}
event: message_stop
data: {"type":"message_stop"}
content_block_delta에 thinking 필드가 포함될 수 있습니다:event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"Let me think about this problem..."}}
오류 처리
시스템은 업스트림 Claude API 오류를 처리하고 표준화된 오류 응답 형식을 반환합니다.| 오류 유형 | HTTP 상태 코드 | 설명 |
|---|---|---|
invalid_request | 400 | 요청 매개변수 오류 (예: 필수 필드 누락) |
authentication_error | 401 | 유효하지 않거나 권한 없는 API 키 |
rate_limit_error | 429 | 요청 속도 제한 초과 |
upstream_error | 500 | 업스트림 서비스 오류 |
gravitex_api_error | 500 | 시스템 내부 오류 |
{
"error": {
"type": "invalid_request",
"message": "field messages is required"
}
}
/v1/chat/completions와 비교
| 기능 | /v1/messages | /v1/chat/completions |
|---|---|---|
| 인증 | Authorization: Bearer | Authorization: Bearer |
| 응답 형식 | Anthropic 네이티브 형식 | OpenAI 호환 형식 |
| 확장 사고 | 네이티브 thinking 매개변수 | reasoning_effort 또는 reasoning 매개변수 |
| 도구 호출 | 네이티브 tools 및 tool_choice | OpenAI 호환 형식 |
| 적합한 클라이언트 | Anthropic SDK, Claude Code | OpenAI SDK, 호환 클라이언트 |
- Claude Code 또는 기타 Anthropic 네이티브 클라이언트를 사용하는 경우
/v1/messages엔드포인트 사용을 권장합니다 - OpenAI SDK를 사용하거나 OpenAI 형식 호환이 필요한 경우
/v1/chat/completions엔드포인트 사용을 권장합니다 - 두 엔드포인트의 기능은 본질적으로 동일하며, 주요 차이는 요청/응답 형식에 있습니다
참고 사항
max_tokens는 필수 매개변수이며 0보다 커야 합니다messages배열은 비어 있을 수 없습니다- 확장 사고 사용 시
budget_tokens는 1024보다 커야 합니다 - 확장 사고는 사고 과정을 보려면 스트리밍 출력이 필요합니다
- 도구 호출은 여러 라운드의 상호작용이 필요합니다: 1라운드에서 도구 호출 요청 반환, 2라운드에서 도구 실행 결과 반환
- 이미지 입력은 base64 인코딩이 필요합니다
- 스트리밍 출력을 사용하면 첫 토큰 응답 시간과 상호작용 경험을 개선할 수 있습니다
- 도구 호출에는 모델 응답 차단을 방지하기 위한 적절한 타임아웃 및 재시도 메커니즘이 있어야 합니다
- 확장 사고는 복잡한 문제에 대한 추론 품질을 크게 향상시킬 수 있습니다
관련 리소스
Chat Completions (OpenAI 호환)
OpenAI 호환 채팅 엔드포인트 문서 보기
모델 목록
지원되는 모든 모델 정보 보기