OpenAI 네이티브 형식(ChatCompletions)

curl --request POST \
  --url https://api.gravitex.ai/v1/chat/completions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "messages": [
    {}
  ],
  "temperature": 123,
  "stream": true,
  "max_tokens": 123,
  "top_p": 123
}
'

import requests

url = "https://api.gravitex.ai/v1/chat/completions"

payload = {
    "model": "<string>",
    "messages": [{}],
    "temperature": 123,
    "stream": True,
    "max_tokens": 123,
    "top_p": 123
}
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: [{}],
    temperature: 123,
    stream: true,
    max_tokens: 123,
    top_p: 123
  })
};

fetch('https://api.gravitex.ai/v1/chat/completions', 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/chat/completions",
  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' => [
        [
                
        ]
    ],
    'temperature' => 123,
    'stream' => true,
    'max_tokens' => 123,
    'top_p' => 123
  ]),
  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/chat/completions"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\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/chat/completions")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gravitex.ai/v1/chat/completions")

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  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "glm-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Artificial intelligence is a branch of computer science that aims to create intelligent machines..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 100,
    "total_tokens": 125
  }
}

POST

chat

completions

OpenAI 네이티브 형식(ChatCompletions)

curl --request POST \
  --url https://api.gravitex.ai/v1/chat/completions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "messages": [
    {}
  ],
  "temperature": 123,
  "stream": true,
  "max_tokens": 123,
  "top_p": 123
}
'

import requests

url = "https://api.gravitex.ai/v1/chat/completions"

payload = {
    "model": "<string>",
    "messages": [{}],
    "temperature": 123,
    "stream": True,
    "max_tokens": 123,
    "top_p": 123
}
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: [{}],
    temperature: 123,
    stream: true,
    max_tokens: 123,
    top_p: 123
  })
};

fetch('https://api.gravitex.ai/v1/chat/completions', 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/chat/completions",
  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' => [
        [
                
        ]
    ],
    'temperature' => 123,
    'stream' => true,
    'max_tokens' => 123,
    'top_p' => 123
  ]),
  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/chat/completions"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\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/chat/completions")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.gravitex.ai/v1/chat/completions")

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  \"temperature\": 123,\n  \"stream\": true,\n  \"max_tokens\": 123,\n  \"top_p\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "glm-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Artificial intelligence is a branch of computer science that aims to create intelligent machines..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 100,
    "total_tokens": 125
  }
}

소개

OpenAI 호환 대규모 언어 모델을 사용해 대화형 응답을 생성하는 범용 텍스트 채팅 API입니다. 통합 API 인터페이스를 통해 OpenAI, Claude, DeepSeek, Grok, Tongyi Qianwen 등 여러 주요 대형 모델을 호출할 수 있습니다.

인증

string

필수

Bearer Token, 예: Bearer sk-xxxxxxxxxx

요청 매개변수

string

필수

모델 식별자, 지원 모델:

OpenAI 시리즈: gpt-5.5, gpt-5.4, gpt-5.4-pro, gpt-5.4-mini, gpt-5.4-nano, gpt-4o 등
Claude 시리즈: claude-opus-4-8, claude-opus-4-7, claude-opus-4-6, claude-sonnet-4-5-20250929, claude-haiku-4-5-20251001 등
DeepSeek 시리즈: deepseek-v4-pro, deepseek-v4-flash, deepseek-v3-1-250821, deepseek-v3, deepseek-r1 등
Grok 시리즈: grok-4, grok-4-fast-reasoning, grok-3 등
Gemini 시리즈: gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview, nano-banana-pro 및 -thinking/-nothinking / -thinking-<budget> / -thinking-low/-thinking-high 변형
국산 모델: glm-5, glm-4.7, doubao-seed-1-8-251228 (Doubao Seed 시리즈), qwen3-coder-plus, kimi-k2.5 등

array

필수

대화 메시지 목록, 각 요소는 role(user/system/assistant)과 content를 포함합니다

number

기본값:"0.7"

무작위성 제어, 0-2 범위, 값이 높을수록 응답이 더 무작위적입니다

boolean

기본값:"false"

스트리밍 출력 사용 여부, SSE 형식의 청크 데이터를 반환합니다

number

생성할 최대 토큰 수, 응답 길이를 제어합니다

number

핵 샘플링 매개변수, 0-1 범위, 생성 다양성을 제어합니다

기본 예시

비스트리밍 요청
스트리밍 요청 (SSE)
Python Example

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant"},
      {"role": "user", "content": "Briefly introduce artificial intelligence"}
    ],
    "temperature": 0.7
  }'

curl -N -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "doubao-seed-1-8-251228",
    "stream": true,
    "messages": [
      {"role": "system", "content": "You are a helpful assistant"},
      {"role": "user", "content": "Briefly introduce artificial intelligence"}
    ]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.gravitex.ai/v1"
)

# Non-streaming
completion = client.chat.completions.create(
    model="glm-5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "Briefly introduce artificial intelligence"}
    ],
    temperature=0.7
)
print(completion.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="doubao-seed-1-8-251228",
    messages=[
        {"role": "user", "content": "Briefly introduce artificial intelligence"}
    ],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "glm-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Artificial intelligence is a branch of computer science that aims to create intelligent machines..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 100,
    "total_tokens": 125
  }
}

고급 기능

도구 호출 (Functions / Tools)

GPT, Claude, DeepSeek, Grok, Tongyi Qianwen 등의 모델에 적용 가능한 OpenAI 호환 도구 호출 형식을 지원합니다.

1단계: 모델이 도구 호출 반환
2단계: 도구 실행 결과 반환

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "user", "content": "What'\''s the weather in Shanghai?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get weather information by city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"}
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

모델이 tool_calls를 반환한 후에는 도구를 실행하고 결과를 모델에 다시 전달해야 합니다:

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "user", "content": "What'\''s the weather in Shanghai?"},
      {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_xxx",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"Shanghai\"}"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "call_xxx",
        "content": "{\"temp\":\"22°C\",\"condition\":\"Cloudy\",\"aqi\":53}"
      }
    ]
  }'

tool_call_id는 1단계에서 반환된 ID와 일치해야 합니다
도구 실행이 실패하면 읽을 수 있는 오류 정보를 반환하여 이후 완성이 차단되지 않도록 합니다
2단계에서도 스트리밍 출력을 지원합니다

구조화된 출력 (JSON Schema)

response_format 매개변수를 통해 출력 형식을 제어할 수 있으며, GPT, Claude, Grok 등의 모델에 적용됩니다.

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "doubao-seed-1-8-251228",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "Answer",
        "schema": {
          "type": "object",
          "properties": {
            "summary": {"type": "string"}
          },
          "required": ["summary"]
        }
      }
    },
    "messages": [
      {"role": "user", "content": "Return a JSON containing a summary field"}
    ]
  }'

엄격한 구조화된 출력이 필요한 경우 temperature 값을 낮추는 것(예: 0.1-0.3)과 적절한 max_tokens 설정을 권장하여 일관성을 높입니다.

사고(Thinking) 기능

일부 모델은 사고(Thinking/Reasoning) 기능을 지원하여, 응답 생성 시 추론 과정을 표시할 수 있습니다. 모델마다 구현 방식이 다릅니다:

DeepSeek
Tongyi Qianwen
Gemini

DeepSeek 모델은 thinking 필드를 통해 사고 기능을 활성화할 수 있습니다:

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "deepseek-v3-1-250821",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant"},
      {"role": "user", "content": "Give a medium-difficulty geometry problem and solve it step by step"}
    ],
    "thinking": {"type": "enabled"}
  }'

기본 thinking.type은 "disabled"이며, 활성화하려면 "enabled"로 명시적으로 설정해야 합니다
사고 기능의 출력 형태는 모델 버전에 따라 다를 수 있습니다
더 나은 대화형 경험을 위해 stream: true와 함께 사용하는 것을 권장합니다

Tongyi Qianwen은 심층 사고 기능을 지원하며, 스트리밍 출력이 필요합니다:

curl -N -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "qwen3-omni-flash",
    "stream": true,
    "enable_thinking": true,
    "parameters": {
      "incremental_output": true
    },
    "messages": [
      {"role": "system", "content": "You are an excellent mathematician"},
      {"role": "user", "content": "What is the formula for Tower of Hanoi"}
    ]
  }'

추론 과정을 content에 인라인 삽입:클라이언트가 reasoning_content를 표시하지 않는 경우, gravitex_thinking_to_content: true를 사용하여 추론 내용을 content에 인라인으로 삽입할 수 있습니다:

curl -N -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "qwen3-omni-flash",
    "stream": true,
    "enable_thinking": true,
    "gravitex_thinking_to_content": true,
    "parameters": {
      "incremental_output": true
    },
    "messages": [
      {"role": "user", "content": "What is the formula for Tower of Hanoi"}
    ]
  }'

Tongyi Qianwen의 심층 사고 기능은 반드시 stream: true와 함께 사용해야 합니다. enable_thinking: true를 설정했지만 stream: false인 경우, 업스트림 오류를 방지하기 위해 시스템이 자동으로 심층 사고를 비활성화합니다.

Gemini OpenAI 호환 전체 문서(필드 매핑, extra_body, 사용량, thinking)는 Gemini OpenAI 형식(Chat)을 참조하세요. 빠른 참조:

모델 접미사: -thinking(자동 예산); -thinking-<number> 정밀 예산(예: gemini-2.5-flash-thinking-8192); -nothinking 비활성화; gemini-3-pro-preview-thinking-low/high로 레벨 직접 지정
extra_body 설정: extra_body.google.thinking_config.thinking_budget + include_thoughts; 특수 값: -1 자동 활성화, 0 비활성화, >0 특정 예산; stream: true 필요
reasoning_effort: -thinking 사용 시 max_tokens가 설정되지 않은 경우 사용 가능(low/medium/high ≈ 예산의 20%/50%/80%)
Gemini 3 Pro Preview: thinking_level(LOW/HIGH, 기본값 HIGH) 사용, 검색과 조합 가능
검색 활성화: 권장 OpenAI 호환 도구 "tools":[{"type":"function","function":{"name":"googleSearch"}}]; 또는 extra_body.google.tools:[{"googleSearch":{}}]로 전달
참고: thinking 어댑터는 서버 측에서 활성화되어야 합니다; thinking 예산은 출력 토큰에 포함됩니다; reasoning_content를 보려면 stream: true를 사용하세요

예시(2.5, 특정 예산):

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gemini-3-flash-preview",
    "messages": [
      {"role":"user","content":"Give a medium-difficulty geometry problem and analyze it step by step."}
    ],
    "extra_body": {
      "google": {
        "thinking_config": { "thinking_budget": 6000, "include_thoughts": true }
      }
    },
    "stream": true
  }'

예시(3 Pro Preview thinking + 검색):

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "gemini-3-pro-preview",
    "messages": [
      {"role":"user","content":"Google search the weather in Guangzhou today"}
    ],
    "generationConfig": {
      "thinkingConfig": { "thinkingLevel": "LOW" }
    },
    "tools": [
      { "type": "function", "function": { "name": "googleSearch" } }
    ],
    "stream": true
  }'

Tongyi Qianwen 확장 기능

Tongyi Qianwen 모델은 검색, 음성 인식 등의 확장 기능을 지원합니다. 모든 확장 매개변수는 parameters 객체에 넣어야 합니다.

검색 기능
음성 인식

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "qwen3-omni-flash",
    "messages": [
      {"role": "user", "content": "Please first search for recent common misconceptions about Fermat'\''s Last Theorem, then answer"}
    ],
    "stream": true,
    "enable_thinking": true,
    "parameters": {
      "enable_search": true,
      "search_options": {
        "region": "CN",
        "recency_days": 30
      },
      "incremental_output": true
    }
  }'

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "qwen3-omni-flash",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "parameters": {
      "asr_options": {
        "language": "zh"
      }
    }
  }'

Tongyi Qianwen의 모든 확장 매개변수(enable_search, search_options, asr_options, temperature, top_p 등)는 요청 본문 최상위가 아닌 parameters 객체에 넣어야 합니다.

웹 검색 기능

일부 모델은 실시간 웹 검색을 지원하여 최신 정보에 접근하고 응답에 인용 출처를 포함할 수 있습니다.

Claude 웹 검색
Grok 실시간 검색

Claude 모델은 web_search_options 매개변수로 웹 검색 기능을 활성화할 수 없으므로, 도구 호출을 통해서만 구현할 수 있으며 네트워크 및 프롬프트 이유로 불안정할 수 있습니다. 자세한 내용은 위의 도구 호출(Functions / Tools)을 참조하세요.기본 예시(도구 호출 흐름 표시):

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "user", "content": "What are the latest news about artificial intelligence?"},
      {
        "role": "assistant",
        "content": "I'\''ll help you search for the latest news about artificial intelligence.",
        "tool_calls": [
          {
            "id": "toolu_xxx",
            "type": "function",
            "function": {
              "name": "WebSearch",
              "arguments": "{\"query\": \"artificial intelligence latest news 2025\"}"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "toolu_xxx",
        "name": "WebSearch",
        "content": "Web search results for query: \"artificial intelligence latest news 2025\"..."
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

위치 정보 포함 예시(도구 호출 흐름 표시):

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "user", "content": "What'\''s the weather in Shanghai today?"},
      {
        "role": "assistant",
        "content": "I'\''ll help you search for today'\''s weather in Shanghai.",
        "tool_calls": [
          {
            "id": "toolu_xxx",
            "type": "function",
            "function": {
              "name": "WebSearch",
              "arguments": "{\"query\": \"Shanghai today weather\"}"
            }
          }
        ]
      },
      {
        "role": "tool",
        "tool_call_id": "toolu_xxx",
        "name": "WebSearch",
        "content": "Web search results for query: \"Shanghai today weather\"..."
      }
    ],
    "web_search_options": {
      "search_context_size": "medium",
      "user_location": {
        "approximate": {
          "timezone": "Asia/Shanghai",
          "country": "CN",
          "region": "Shanghai",
          "city": "Shanghai"
        }
      }
    }
  }'

검색 기능은 응답 시간과 토큰 소비(검색 결과 내용 포함)를 증가시킵니다
검색 결과는 응답에 인용 출처가 자동으로 포함됩니다
지원 모델: Claude Sonnet 4, Claude 3 Opus 등
다중 턴 대화에서 도구 호출과 결과는 메시지 기록에 표시되며, 모델은 이전 검색 결과를 바탕으로 대화를 이어갈 수 있습니다

안정성 안내:

웹 검색 기능은 업스트림 프록시 서비스 및 외부 검색 서비스에 의존하며, 다음과 같은 불안정성이 있을 수 있습니다:
- 네트워크 변동: 네트워크 연결 문제로 검색 요청이 타임아웃되거나 실패할 수 있습니다
- 서비스 제한: 검색 서비스에 속도 제한, 타임아웃 제한 또는 일시적 사용 불가가 있을 수 있습니다
- 검색 결과 품질: 일부 쿼리는 관련 정보를 찾지 못하거나 검색 결과 품질이 낮을 수 있습니다
- 모델 판단: 모델은 질문에 따라 검색 필요 여부를 자동으로 판단하며, 일부 경우 검색이 트리거되지 않을 수 있습니다
이는 웹 검색 기능의 고유한 특성입니다. 다음을 권장합니다:
- 중요한 시나리오에서 재시도 메커니즘 구현
- 검색 실패 시 우아한 성능 저하 처리(예: 모델의 지식 베이스로 답변)
- 실시간성이 매우 높은 시나리오에서 웹 검색에 전적으로 의존하지 않기

Grok 모델은 search_parameters 매개변수를 통해 실시간 검색을 지원합니다.

object

검색 매개변수 설정

mode (선택): 검색 모드, 옵션:
- "off": 검색 비활성화
- "auto": 모델이 검색 필요 여부를 자동 판단(권장)
- "on": 검색 강제 사용
return_citations (선택): 응답에 인용 링크 반환 여부, 기본값 true

기본 예시:

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "grok-4",
    "messages": [
      {"role": "user", "content": "What are the latest developments in AI in 2026?"}
    ],
    "search_parameters": {
      "mode": "auto"
    }
  }'

검색 강제 예시:

curl -X POST "https://api.gravitex.ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "grok-4",
    "messages": [
      {"role": "user", "content": "What are the latest tech news?"}
    ],
    "search_parameters": {
      "mode": "on",
      "return_citations": true
    }
  }'

Python Example:

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.gravitex.ai/v1"
)

completion = client.chat.completions.create(
    model="grok-4",
    messages=[
        {"role": "user", "content": "What are the latest developments in AI in 2026?"}
    ],
    extra_body={
        "search_parameters": {
            "mode": "auto"
        }
    }
)
print(completion.choices[0].message.content)

모델이 검색 필요 여부를 자동 판단하도록 "auto" 모드 사용을 권장합니다
검색 기능은 응답 시간을 증가시키지만 최신 실시간 정보에 접근할 수 있습니다
지원 모델: grok-4, grok-3 시리즈 등
검색 결과는 응답에 인용 출처가 포함됩니다

GPT 파일 입력 (Responses API)

GPT-5 등의 모델은 파일 입력 기능을 지원하며, /v1/chat/completions가 아닌 /v1/responses 엔드포인트를 통해 호출해야 합니다.

파일 URL로 업로드
Base64 인코딩으로 업로드

외부 URL을 연결하여 PDF 파일을 업로드할 수 있습니다:

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.gravitex.ai/v1/responses?api-version=2025-03-01-preview"
)

response = client.responses.create(
    model="gpt-5.2",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Analyze this letter and summarize its key points"
                },
                {
                    "type": "input_file",
                    "file_url": "https://www.example.com/document.pdf"
                }
            ]
        }
    ]
)
print(response.output_text)

Base64로 인코딩된 입력으로 전송:

import base64
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.gravitex.ai/v1"
)

with open("document.pdf", "rb") as f:
    data = f.read()

base64_string = base64.b64encode(data).decode("utf-8")

response = client.responses.create(
    model="gpt-5.2",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_file",
                    "filename": "document.pdf",
                    "file_data": f"data:application/pdf;base64,{base64_string}"
                },
                {
                    "type": "input_text",
                    "text": "What is the main content of this document?"
                }
            ]
        }
    ]
)
print(response.output_text)

파일 크기 제한: 단일 파일 50MB 이하, 단일 요청의 모든 파일 총 크기 50MB 이하
지원 모델: gpt-4o, gpt-4o-mini, gpt-5-chat 및 텍스트·이미지 입력을 지원하는 기타 모델

Grok 추론(Reasoning) 기능

Grok 모델(특히 grok-4-fast-reasoning)은 추론 기능을 지원합니다. 활성화 시 usage.completion_tokens_details.reasoning_tokens에 추론 과정에서 소비된 토큰 수가 표시됩니다. 자세한 내용은 아래 usage 필드 설명을 참고하세요.

usage 필드 설명

/v1/chat/completions 호출 시 응답의 usage 객체에 토큰 사용량 통계가 포함됩니다. 먼저 공통 필드(일반 대화 모델 시나리오)를 설명하고, 특정 시나리오에서만 0이 아닌 값이 나타나는 전용 필드를 설명합니다.

공통 필드

적용 범위: GPT 시리즈, Claude 대화/사고 모델, Gemini, DeepSeek 등 /v1/chat/completions를 통한 텍스트 대화 시나리오. 게이트웨이가 내부적으로 Claude Messages 프로토콜 또는 이미지 생성 모델을 호출할 때만 나타나는 필드는 포함하지 않습니다 — 특수 시나리오 전용 필드를 참고하세요.

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1752345600,
  "model": "gpt-5.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "모델의 응답 내용입니다"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 85,
    "total_tokens": 205,

    "prompt_tokens_details": {
      "cached_tokens": 30,
      "cache_write_tokens": 5,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0,
      "reasoning_tokens": 42,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    },

    "input_tokens": 120,
    "output_tokens": 85,
    "input_tokens_details": null
  }
}

필드	값이 있는 경우	설명
`prompt_tokens`	항상	입력 토큰 총수
`completion_tokens`	항상	출력 토큰 총수
`total_tokens`	항상	`prompt_tokens + completion_tokens`
`prompt_tokens_details.cached_tokens`	모델/채널이 prompt caching을 지원할 때	캐시 히트로 캐시 요금이 적용되는 입력 토큰 수(OpenAI 네이티브 캐시, Gemini 암시적 캐시, Claude 캐시 읽기 모두 이 필드에 반영)
`prompt_tokens_details.cache_write_tokens`	GPT-5.6 이상, 명시적 prompt cache 활성화 시	이번 요청에서 새로 캐시에 기록된 토큰 수, 캐시 기록 요금 적용
`prompt_tokens_details.audio_tokens`	오디오 입력 모델 사용 시(예: `gpt-4o-audio-preview`)	입력 오디오 부분에서 소비된 토큰 수
`prompt_tokens_details.text_tokens` / `image_tokens`	대부분의 순수 텍스트 대화에서 `0`	입력 텍스트/이미지 토큰 분류, 순수 텍스트 대화에서는 보통 채워지지 않지만 필드 자체는 항상 존재
`completion_tokens_details.reasoning_tokens`	추론 모델만(GPT o1/o3/GPT-5 시리즈, Claude 확장 사고, Gemini thinking)	내부 추론에 소비된 토큰 수, 최종 응답 텍스트에는 나타나지 않지만 출력 요금 적용
`completion_tokens_details.audio_tokens`	오디오 출력 모델 사용 시	출력 오디오 부분에서 소비된 토큰 수
`completion_tokens_details.accepted_prediction_tokens` / `rejected_prediction_tokens`	OpenAI Predicted Outputs 사용 시	예측 내용에 일치/불일치한 토큰 수, 불일치 부분도 출력 요금 적용
`completion_tokens_details.text_tokens` / `image_tokens`	순수 텍스트 대화에서 `0`	아래 「image_tokens 관련」 참고
`input_tokens` / `output_tokens`	항상	`prompt_tokens` / `completion_tokens`와 동일한 값, 일부 업스트림 프로토콜 호환용 별칭
`input_tokens_details`	대화 시나리오에서 대부분 `null`	예약 필드, 일반 대화 요청에서는 채워지지 않음

prompt_tokens_details / completion_tokens_details 객체는 응답에 항상 존재하며, 내부 하위 필드가 모두 0이어도 생략되지 않습니다. 0은 「미지원」이 아니라 「이번 요청에서 사용되지 않음」을 의미합니다.
completion_tokens_details.image_tokens(및 prompt_tokens_details.image_tokens)는 필드 구조가 항상 존재하기 때문에 공통 문서에 포함되지만, 0이 아닌 값은 특수 시나리오(Claude/이미지 생성 모델)에서만 나타납니다. 특수 시나리오 전용 필드를 참고하세요.
reasoning_tokens는 모델 간 공통 개념입니다. 업스트림이 OpenAI 추론 모델, Claude 확장 사고, Gemini thinking 중 어느 것이든, 해당 호출에서 「사고」 기능이 활성화되면 이 단일 필드에 반영됩니다.

특수 시나리오 전용 필드

다음 필드는 특정 경우에만 0이 아닌 값이 나타납니다. 요청은 /v1/chat/completions로 들어가지만, 게이트웨이가 내부적으로 다른 프로토콜(Claude Messages 프로토콜 / 이미지 생성 모델)로 변환해 업스트림을 호출하고, 변환된 usage에 「네이티브 프로토콜 전용」필드가 포함됩니다.

시나리오 1: 내부적으로 Claude 호출 (`/v1/chat/completions` → `/v1/messages`)

OpenAI 형식으로 Claude 모델을 요청하면 게이트웨이가 요청을 Anthropic Messages 프로토콜로 변환하고, Claude의 usage를 OpenAI 형식으로 다시 변환합니다. Claude의 캐시 메커니즘은 OpenAI보다 세분화되어 있으며(5분/1시간 TTL 2단계 요금), 아래 전용 필드로 표현됩니다:

"usage": {
  "prompt_tokens": 120,
  "completion_tokens": 85,
  "total_tokens": 205,
  "prompt_tokens_details": {
    "cached_tokens": 30,
    "cached_creation_tokens": 10
  },
  "completion_tokens_details": {
    "reasoning_tokens": 42
  },
  "claude_cache_creation_5_m_tokens": 8,
  "claude_cache_creation_1_h_tokens": 2
}

필드	설명
`prompt_tokens_details.cached_creation_tokens`	Claude의 `cache_creation_input_tokens`에 해당: 이번 요청에서 prompt cache 기록을 위해 추가로 소비된 입력 토큰 수(이 총수가 아래 두 필드로 TTL별 분류됨)
`claude_cache_creation_5_m_tokens`	위 `cached_creation_tokens` 중 5분 TTL 등급으로 캐시에 기록된 토큰 수
`claude_cache_creation_1_h_tokens`	위 `cached_creation_tokens` 중 1시간 TTL 등급으로 캐시에 기록된 토큰 수(해당 등급 단가가 더 높음)

prompt_tokens_details.cached_tokens, completion_tokens_details.reasoning_tokens도 Claude 모델 호출 시 값이 있습니다(각각 Claude 캐시 읽기 토큰 수, 확장 사고 토큰 수에 해당). 하지만 이 두 필드는 모델 간 공통 필드로 공통 필드에서 이미 설명했습니다.

시나리오 2: 내부적으로 이미지 생성 모델 호출 (`/v1/chat/completions` → `/v1/images/generations` 의미)

일부 이미지 생성 모델(예: Gemini 네이티브 이미지 출력, gpt-image 시리즈)은 원래 공식 /v1/images/generations 인터페이스의 usage 구조(input_tokens/output_tokens + 모달리티 분류)를 사용합니다. 사용자가 /v1/chat/completions로 대화형 이미지 생성을 호출하면 게이트웨이가 이 정보를 chat 형식 usage에 매핑합니다:

"usage": {
  "prompt_tokens": 50,
  "completion_tokens": 1290,
  "total_tokens": 1340,
  "prompt_tokens_details": {
    "text_tokens": 50,
    "image_tokens": 0
  },
  "completion_tokens_details": {
    "text_tokens": 0,
    "image_tokens": 1290
  },
  "generated_images": 1
}

필드	설명
`completion_tokens_details.image_tokens`	공식 `/v1/images/generations`의 이미지 출력 토큰 수, chat 형식으로 매핑 후 이 필드에 반영, 이미지 요금 비율(`ImageCompletionRatio`)로 과금
`prompt_tokens_details.image_tokens`	입력에 이미지가 포함된 경우(예: 이미지 편집/이미지-투-이미지) 소비된 이미지 토큰 수
`generated_images`	업스트림에서 실제 생성된 이미지 장수(장당 과금 모델은 토큰 수 대신 이 값으로 과금, 「4장 요청했지만 1장만 생성」 시 과다 과금 방지)

시나리오 3: 채널 프로토콜 차이로 인한 필드

다음 두 필드는 「변환」된 것이 아니라 특정 채널에서 업스트림 응답 필드를 그대로 전달한 것입니다. 주류 모델을 정상 사용하면 거의 만나지 않습니다:

필드	발생 조건	설명
`prompt_cache_hit_tokens`	DeepSeek 채널, 업스트림이 DeepSeek 고유 필드명으로 캐시 정보 반환 시	DeepSeek 공식 API는 캐시 히트를 `cached_tokens`가 아닌 `prompt_cache_hit_tokens`로 표현. 게이트웨이는 공통 `prompt_tokens_details.cached_tokens`에도 동기 매핑하지만 원본 필드도 최상위에 유지
`cost`	OpenRouter 채널, 업스트림 응답에 USD 비용 포함 시	OpenRouter 전용 필드, 일반 채널(공식 OpenAI/Claude/Gemini 등)에서는 나타나지 않음

응답 형식

비스트리밍 응답
스트리밍 응답

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "glm-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Response content..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 100,
    "total_tokens": 125
  }
}

usage 필드 전체 설명은 위 usage 필드 설명을 참고하세요.

스트리밍 응답은 SSE(Server-Sent Events) 형식으로 반환되며, 각 청크에는 부분 내용이 포함됩니다:

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"doubao-seed-1-8-251228","choices":[{"index":0,"delta":{"content":"回"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1234567890,"model":"doubao-seed-1-8-251228","choices":[{"index":0,"delta":{"content":"复"},"finish_reason":null}]}

data: [DONE]

마지막 청크에는 보통 usage 통계가 포함됩니다.

오류 처리

예외 유형	발생 시나리오	반환 메시지
AuthenticationError	유효하지 않거나 권한 없는 API 키	Error: Invalid or unauthorized API key
NotFoundError	모델이 존재하지 않거나 지원되지 않음	Error: Model [model] does not exist or is not supported
APIConnectionError	네트워크 중단 또는 서버 미응답	Error: Cannot connect to API server
APIError	요청 형식 오류 및 기타 서버 측 예외	API request failed: [error details]

지원 모델 시리즈

OpenAI 시리즈

GPT-5.5, GPT-5.4 family (5.4 / Pro / Mini / Nano), GPT-4o, GPT-4o Mini

Claude 시리즈 (Anthropic)

Claude Sonnet 4, Claude 3 Opus, Claude 3 Haiku

DeepSeek 시리즈

DeepSeek V3, DeepSeek R1

Grok 시리즈 (xAI)

Grok-4, Grok-3, Grok-3-fast, Grok-4-fast-reasoning

Tongyi Qianwen 시리즈 (Qwen)

Qwen3-omni-flash 등

Doubao Seed 시리즈

doubao-seed-1-8-251228 등

기타 모델

Gemini 시리즈, GLM 시리즈(glm-5 포함), Kimi 시리즈 등

전체 모델 목록은 모델 정보 페이지를 참조하세요.

참고 사항

messages 목록에서 system 역할은 모델 동작을 설정하고, user 역할은 사용자 질문용입니다
다중 턴 대화는 기록(assistant 역할 응답 포함)을 추가해야 합니다
openai 라이브러리 필요: pip install openai
모델마다 특정 기능 지원 수준이 다를 수 있으므로, 사용 전 해당 모델 문서를 확인하는 것을 권장합니다

스트리밍 출력을 사용하면 첫 토큰 응답 시간과 대화형 경험을 개선할 수 있습니다
도구 호출에는 모델 응답이 차단되지 않도록 적절한 타임아웃 및 재시도 메커니즘이 필요합니다
Tongyi Qianwen 확장 매개변수는 반드시 parameters 객체에 넣어야 합니다

FAQ

채팅 인터페이스 FAQ 보기

모델 목록

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

OpenAI 네이티브 형식(Responses)Gemini OpenAI 형식(Chat)

API 문서

대화 및 텍스트

안전 및 오디오

이미지 시리즈

비디오 시리즈

텍스트 완성 및 임베딩

인터페이스 모듈

OpenAI 네이티브 형식(ChatCompletions)

소개

인증

요청 매개변수

기본 예시

고급 기능

도구 호출 (Functions / Tools)

구조화된 출력 (JSON Schema)

사고(Thinking) 기능

Tongyi Qianwen 확장 기능

웹 검색 기능

GPT 파일 입력 (Responses API)

Grok 추론(Reasoning) 기능

usage 필드 설명

공통 필드

특수 시나리오 전용 필드

시나리오 1: 내부적으로 Claude 호출 (`/v1/chat/completions` → `/v1/messages`)

시나리오 2: 내부적으로 이미지 생성 모델 호출 (`/v1/chat/completions` → `/v1/images/generations` 의미)

시나리오 3: 채널 프로토콜 차이로 인한 필드

응답 형식

오류 처리

지원 모델 시리즈

OpenAI 시리즈

Claude 시리즈 (Anthropic)

DeepSeek 시리즈

Grok 시리즈 (xAI)

Tongyi Qianwen 시리즈 (Qwen)

Doubao Seed 시리즈

기타 모델

참고 사항

관련 자료

FAQ

모델 목록

​소개

​인증

​요청 매개변수

​기본 예시

​고급 기능

​도구 호출 (Functions / Tools)

​구조화된 출력 (JSON Schema)

​사고(Thinking) 기능

​Tongyi Qianwen 확장 기능

​웹 검색 기능

​GPT 파일 입력 (Responses API)

​Grok 추론(Reasoning) 기능

​usage 필드 설명

​공통 필드

​특수 시나리오 전용 필드

​시나리오 1: 내부적으로 Claude 호출 (/v1/chat/completions → /v1/messages)

​시나리오 2: 내부적으로 이미지 생성 모델 호출 (/v1/chat/completions → /v1/images/generations 의미)

​시나리오 3: 채널 프로토콜 차이로 인한 필드

​응답 형식

​오류 처리

​지원 모델 시리즈

​OpenAI 시리즈

​Claude 시리즈 (Anthropic)

​DeepSeek 시리즈

​Grok 시리즈 (xAI)

​Tongyi Qianwen 시리즈 (Qwen)

​Doubao Seed 시리즈

​기타 모델

​참고 사항

​관련 자료

FAQ

모델 목록

소개

인증

요청 매개변수

기본 예시

고급 기능

도구 호출 (Functions / Tools)

구조화된 출력 (JSON Schema)

사고(Thinking) 기능

Tongyi Qianwen 확장 기능

웹 검색 기능

GPT 파일 입력 (Responses API)

Grok 추론(Reasoning) 기능

usage 필드 설명

공통 필드

특수 시나리오 전용 필드

시나리오 1: 내부적으로 Claude 호출 (`/v1/chat/completions` → `/v1/messages`)

시나리오 2: 내부적으로 이미지 생성 모델 호출 (`/v1/chat/completions` → `/v1/images/generations` 의미)

시나리오 3: 채널 프로토콜 차이로 인한 필드

응답 형식

오류 처리

지원 모델 시리즈

OpenAI 시리즈

Claude 시리즈 (Anthropic)

DeepSeek 시리즈

Grok 시리즈 (xAI)

Tongyi Qianwen 시리즈 (Qwen)

Doubao Seed 시리즈

기타 모델

참고 사항

관련 자료