Claude 네이티브 형식

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": {},
  "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": {},
    "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: {},
    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' => [
        
    ],
    '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  \"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  \"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  \"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
  }
}

POST

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": {},
  "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": {},
    "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: {},
    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' => [
        
    ],
    '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  \"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  \"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  \"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-opus-4-8 - Claude Opus 4.8 (최신, 가장 강력한 추론)
claude-opus-4-7 - Claude Opus 4.7
claude-opus-4-6 - Claude Opus 4.6
claude-sonnet-4-6 - Claude Sonnet 4.6 (최신, 균형 잡힌 성능)
claude-opus-4-5-20251101 - Claude Opus 4.5
claude-haiku-4-5-20251001 - Claude Haiku 4.5 (최신, 가장 빠름)
claude-sonnet-4-5-20250929 - Claude Sonnet 4.5
claude-opus-4-1-20250805 - Claude Opus 4.1
claude-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의 심층 추론 기능을 활성화합니다.

object

추적 및 디버깅용 요청 메타데이터.

array

MCP(Model Context Protocol) 서버 설정.

object

컨텍스트 관리 설정. 대화 컨텍스트 처리 방식을 제어합니다.

프롬프트 캐싱

프롬프트 캐싱을 사용하면 자주 사용하는 컨텍스트 콘텐츠를 캐시하여 비용을 크게 절감하고 응답 속도를 향상시킬 수 있습니다. system과 messages에서 cache_control 매개변수를 사용할 수 있습니다.

캐시 제어 매개변수

object

캐시 제어 설정. system 배열 요소와 messages의 content 배열 요소에서 사용할 수 있습니다.

type: 캐시 유형
- "ephemeral": 5분 캐시 (기본값, 가장 비용 효율적)
- "persistent": 1시간 캐시 (장기적으로 안정적인 컨텍스트에 적합)

캐싱 메커니즘

캐시 위치: cache_control이 지정된 마지막 콘텐츠 블록이 캐시됩니다
캐시 임계값: 콘텐츠는 최소 1024 토큰(Claude Sonnet 4.5) 또는 2048 토큰(Claude 3 Haiku) 이상이어야 합니다
캐시 유효 기간:
- ephemeral: 5분간 유효
- persistent: 1시간 유효
비용 절감: 캐시 읽기는 일반 입력보다 90% 저렴합니다

사용 사례

긴 문서 분석: 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는 공식 웹 검색 도구 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?"}
    ]
  }'

Python 예제:

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-10
user_location (선택): 검색 결과의 지역화 정확도를 높이는 사용자 위치 정보
검색 결과는 응답에 인용 출처가 자동으로 포함됩니다
Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 등 지원 모델 포함

1단계: 모델이 도구 호출 요청 반환

{
  "id": "msg_xxx",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_xxx",
      "name": "get_weather",
      "input": {"city": "Shanghai"}
    }
  ],
  "stop_reason": "tool_use"
}

2단계: 도구 실행 결과 반환

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
  }
}

5분 이내 두 번째 요청 (다른 질문, 동일 system):

{
  "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": "persistent"}
          }
        ]
      },
      {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "The main functionality of this code is...[detailed analysis]",
            "cache_control": {"type": "persistent"}
          }
        ]
      },
      {
        "role": "user",
        "content": "How can I optimize the performance of this code?"
      }
    ]
  }'

persistent 캐시의 장점:

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")

캐시 핵심 사항:

콘텐츠는 캐싱을 트리거하려면 ≥ 1024 토큰(Claude Sonnet 4.5) 이상이어야 합니다
ephemeral 캐시는 5분간 유효합니다
persistent 캐시는 1시간 유효합니다
캐시 읽기 비용은 일반 입력보다 90% 저렴합니다
cache_control이 지정된 마지막 블록이 캐시됩니다
캐시는 정확한 콘텐츠 일치를 기반으로 하며, 변경 시 캐시가 무효화됩니다

모범 사례:

변경되지 않는 긴 컨텍스트(문서, 코드베이스 등)를 system에 캐싱 활성화와 함께 배치
장기적으로 안정적인 콘텐츠에는 persistent 캐시(1시간) 사용
자주 변경되는 콘텐츠에는 ephemeral 캐시(5분) 사용
다중 턴 대화에서 대화 기록 캐시
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
  }
}

캐시 사용 시 usage 필드:

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 호환 채팅 엔드포인트 문서 보기

모델 목록

지원되는 모든 모델 정보 보기

모델 목록 Gemini 네이티브 형식

API 문서

대화 및 텍스트

안전 및 오디오

이미지 시리즈

비디오 시리즈

텍스트 완성 및 임베딩

인터페이스 모듈

소개

인증

요청 매개변수

프롬프트 캐싱

캐시 제어 매개변수

캐싱 메커니즘

사용 사례

기본 예제

고급 기능

시스템 프롬프트

확장 사고

도구 호출

tool_choice 매개변수 상세

멀티모달 입력 (이미지)

프롬프트 캐싱

응답 형식

오류 처리

/v1/chat/completions와 비교

참고 사항

관련 리소스

Chat Completions (OpenAI 호환)

모델 목록

​소개

​인증

​요청 매개변수

​프롬프트 캐싱

​캐시 제어 매개변수

​캐싱 메커니즘

​사용 사례

​기본 예제

​고급 기능

​시스템 프롬프트

​확장 사고

​도구 호출

​tool_choice 매개변수 상세

​멀티모달 입력 (이미지)

​프롬프트 캐싱

​응답 형식

​오류 처리

​/v1/chat/completions와 비교

​참고 사항

​관련 리소스

Chat Completions (OpenAI 호환)

모델 목록

소개

인증

요청 매개변수

프롬프트 캐싱

캐시 제어 매개변수

캐싱 메커니즘

사용 사례

기본 예제

고급 기능

시스템 프롬프트

확장 사고

도구 호출

tool_choice 매개변수 상세

멀티모달 입력 (이미지)

프롬프트 캐싱

응답 형식

오류 처리

/v1/chat/completions와 비교

참고 사항

관련 리소스