GPT-6 Astra · API

빠른 시작

두 단계면 됩니다: 요청 보내기 → 스트리밍으로 답변 받기. YOUR_API_KEY를 내 키로 바꾸면 아래 명령을 그대로 실행할 수 있습니다. 엔드포인트가 OpenAI Chat Completions와 같으므로 기존 OpenAI 코드는 base_url과 model만 바꾸면 됩니다.

1단계 · 요청 보내기

curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "messages": [{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}]}'

응답(HTTP 200)

{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "gpt-6-astra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "광합성은 식물이 햇빛을 이용해 이산화탄소와 물을 당으로 바꾸고 산소를 내보내는 과정입니다.",
        "reasoning_content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 186,
    "total_tokens": 204,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 144}
  }
}

message.content는 답변이고 message.reasoning_content는 사고 과정입니다. usage는 이 요청에 과금되는 토큰 수이며, 사고 토큰은 completion_tokens에 포함되어 출력 요금으로 과금됩니다.

2단계 · 스트리밍으로 받기(권장)

curl -N https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "stream": true, "messages": [{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}]}'

스트림은 표준 SSE입니다. 각 청크의 본문은 choices[0].delta.content에 담기고, 마지막 청크에는 usage가 담기며, 스트림은 data: [DONE]으로 끝납니다. 답변이 길거나 모델이 먼저 생각해야 할 때는 스트리밍을 쓰세요. 비스트리밍 요청은 약 10분이 지나면 연결이 끊깁니다.

Python(OpenAI SDK)

from openai import OpenAI

client = OpenAI(base_url="https://nezhagate.com/v1", api_key="YOUR_API_KEY")

# 1. 질문 하나에 답변 하나
resp = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}],
)
print(resp.choices[0].message.content)

# 2. 스트리밍
stream = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": "광합성을 한 문장으로 설명해 줘"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

인증

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

콘솔에서 API 키를 만들면 시작할 수 있습니다.

사양 한눈에 보기

요청 파라미터

POST /v1/chat/completions의 요청 본문(JSON)이며, OpenAI Chat Completions와 같습니다. 자주 쓰는 파라미터와 이 모델에서의 실제 동작은 다음과 같습니다:

frequency_penalty와 presence_penalty도 무시됩니다. 그 밖의 OpenAI 파라미터는 보낸 그대로 모델에 전달됩니다.

가격

토큰 단위로 과금하며, 아래 요금(100만 토큰당)은 실시간으로 반영됩니다. 성공한 요청의 실제 사용량만 과금하고, 실패, 시간 초과, 거부된 요청은 과금하지 않습니다. 1크레딧 = $0.005.

예를 들어 입력 2,000 토큰, 출력 1,000 토큰(사고 포함)인 요청 한 건은 약 $0.021입니다.

사고(Thinking)

reasoning_effort에는 low / medium / high / xhigh / max를 쓸 수 있으며, 생략하면 게이트웨이가 medium으로 요청합니다. 단계가 높을수록 더 오래 생각해 더 안정적으로 답하지만, 응답이 느려지고 출력 토큰도 늘어납니다. 간단한 질문에는 low로 충분합니다.

사고 요약은 message.reasoning_content로 반환됩니다(스트리밍에서는 delta.reasoning_content). 단계를 모델 ID에 넣어 gpt-6-astra-low, gpt-6-astra-high, gpt-6-astra-xhigh처럼 써도 효과가 같으며, 과금은 gpt-6-astra 기준입니다.

/v1/responses에서는 사고 깊이를 reasoning.effort에 넣으며, 사고 요약은 reasoning.summary를 직접 설정했을 때만 반환됩니다(게이트웨이가 대신 넣지 않습니다).

사고 토큰은 usage.completion_tokens에 포함되어 출력 요금으로 과금됩니다(일부 모델은 completion_tokens_details.reasoning_tokens에 따로 표시합니다).

프롬프트 캐싱

별도의 파라미터는 필요 없습니다. 반복되는 긴 접두어(같은 시스템 프롬프트, 대화의 앞부분)는 모델 제공사가 자동으로 캐시할 수 있으며, 캐시에 적중한 부분은 더 낮은 캐시 요금으로 과금됩니다. 캐시 여부와 적중량은 모델 제공사가 정합니다. 바뀌지 않는 내용을 메시지 맨 앞에 두면 적중률을 높일 수 있습니다.

캐시에 적중한 토큰 수는 usage.prompt_tokens_details.cached_tokens로 반환되며, 이 부분은 캐시 적중 요금으로, 나머지 입력은 입력 요금으로 과금됩니다.

이미지 입력

content 배열에 image_url 파트를 넣으세요. base64 data URI(data:image/png;base64,...)를 권장하며, 이 방식은 모든 회선에서 읽을 수 있습니다. 공개 이미지 링크는 회선이 직접 내려받아야 해서 일부 회선에서는 가져오지 못하거나 시간이 초과될 수 있습니다. 이미지는 모델 제공사의 규칙에 따라 입력 토큰으로 환산됩니다.

curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "messages": [{"role": "user", "content": [{"type": "text", "text": "이 이미지에 무엇이 있는지 알려 줘"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]}]}'

도구 호출(Function Calling)

tools에 JSON Schema로 함수를 정의하세요. 모델이 함수를 호출하기로 하면 finish_reason: "tool_calls"를 돌려주며, message.tool_calls에 함수 이름과 인자(JSON 문자열)가 담깁니다.

curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "messages": [{"role": "user", "content": "지금 상하이 날씨를 알려 줘"}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Current weather of a city", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]}'

함수를 실행한 뒤 그 결과를 role: "tool" 메시지로(해당 tool_call_id와 함께) 대화에 덧붙여 다시 요청하면, 모델이 이를 바탕으로 최종 답변을 줍니다. tool_choice에는 auto, none, required 또는 특정 함수를 지정할 수 있습니다.

Responses API(/v1/responses)

이 모델은 OpenAI Responses API로도 호출할 수 있습니다. Codex 같은 도구가 쓰는 바로 그 API입니다. 요청과 응답은 OpenAI Responses 형식을 따르며, 입력은 input에, 사고 깊이는 reasoning.effort에 넣습니다.

curl https://nezhagate.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "input": "광합성을 한 문장으로 설명해 줘", "reasoning": {"effort": "medium", "summary": "auto"}}'

이 엔드포인트는 기본 사고 단계를 대신 넣지 않으며 사고 요약도 자동으로 돌려주지 않습니다. 요약이 필요하면 위 예시처럼 "summary": "auto"를 보내세요. 과금은 채팅 엔드포인트와 같으며, 웹 검색은 /v1/chat/completions에서만 제공됩니다.

웹 검색

요청에 "web_search": true를 넣으세요(또는 tools에 {"type": "web_search"} 항목을 넣어도 됩니다). 게이트웨이가 먼저 대화 내용을 바탕으로 실시간 웹 검색을 하고 최대 5개의 결과를 링크와 함께 참고 자료로 모델에 넘기면, 모델이 이를 바탕으로 답하면서 출처를 표시합니다. 검색 자체는 무료이며, 참고 자료는 입력 토큰으로 과금됩니다.

curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "web_search": true, "messages": [{"role": "user", "content": "오늘 주요 기술 뉴스를 알려 줘"}]}'

회선과 안정성

• 모든 모델은 여러 회선으로 제공됩니다. 한 회선에서 오류나 시간 초과가 나거나 회선이 가득 차면, 게이트웨이는 응답을 돌려주기 시작하기 전에 자동으로 다음 회선으로 넘어갑니다. 따로 재시도할 필요가 없고, 두 번 과금되지도 않습니다.
• 스트리밍은 출력을 시작한 뒤에는 회선을 바꾸지 않습니다. 중간에 끊기면 끊기기 전까지 생성된 사용량만큼 과금됩니다(과금과 환불 참고).
• 모든 회선이 가득 차면 게이트웨이가 Retry-After와 함께 429를 돌려줍니다. 그 초만큼 기다린 뒤 다시 시도하세요. 실패한 요청은 과금되지 않습니다. 모델별 상태는 서비스 상태에서 볼 수 있습니다.

오류와 환불

오류는 error 객체(message, type, code, param)로 돌아옵니다. HTTP 상태 코드와 code로 판단하고, message 문구로는 판단하지 마세요. 실패한 요청은 과금되지 않으며, 전체 목록은 오류 코드에 있습니다.

스트리밍이 출력을 시작한 뒤 실패하면 상태 코드는 바뀌지 않습니다. 오류는 error가 담긴 데이터 줄로 오거나, 스트림이 그냥 끝납니다(data: [DONE] 없이). 이런 경우 중단된 것으로 처리하세요.