
이 GPT-6.2 API 가이드는 API 키 발급부터 cURL과 Python OpenAI SDK로 gpt-6.2-sol 또는 gpt-6.2-astra에 동작하는 요청을 보내기까지, Responses와 Chat Completions 두 엔드포인트 모두를 다룹니다. 모든 요청 본문은 2026년 11월 18일 기준 PoYo의 공개 스키마와 OpenAI의 GPT-6.2 마이그레이션 노트를 따릅니다. 프롬프트는 GPT-6.2 Sol 모델 페이지나 GPT-6.2 Astra 모델 페이지에서 먼저 테스트해 볼 수 있습니다.
모델이 처음이라면 GPT-6.2 API 개요에서 제한과 포지셔닝을 확인하세요.
시작하기 전에
PoYo 대시보드에서 키를 만들고 서버에 보관하세요.
export POYO_API_KEY="your-poyo-key"
| 형식 | 엔드포인트 | 사용 시점 |
|---|---|---|
| Responses | POST https://api.poyo.ai/v1/responses | 신규 코드, 함수 도구, 이미지 입력, 추론 강도 |
| Chat Completions | POST https://api.poyo.ai/v1/chat/completions | 기존 Chat Completions 코드, 텍스트 전용 메시지, 도구 없음 |
모든 요청은 Authorization: Bearer $POYO_API_KEY를 보냅니다. 예제는 gpt-6.2-sol을 사용하며, Astra를 쓰려면 gpt-6.2-astra로 바꾸면 됩니다. 요청 구조는 동일합니다.
OpenAI GPT-6.2 가이드의 세 가지 규칙이 아래 모든 예제에 적용됩니다.
temperature나top_p를 보내지 마세요. OpenAI는 이 둘과 함께 Chat Completions에서는logprobs와top_logprobs, Responses에서는top_logprobs도 생략하라고 안내합니다. PoYo 스키마에는 이전 모델용으로temperature와top_p가 아직 남아 있습니다.- 추론 강도를
none으로 설정하지 마세요. API가 거부합니다. - 고정된 지시 사항은
input맨 앞의developer메시지에 넣으세요. GPT-6.2는 최상위instructions를input뒤에 덧붙이므로 캐시 가능한 프리픽스에서 벗어나게 됩니다.
cURL로 첫 GPT-6.2 API 요청 보내기
curl https://api.poyo.ai/v1/responses \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6.2-sol",
"input": [
{"role": "developer", "content": "You are a code reviewer. Be specific and cite line numbers."},
{"role": "user", "content": "Review this function for race conditions: ..."}
],
"reasoning": {"effort": "medium"},
"max_output_tokens": 8000,
"store": false
}'
model과 input은 필수입니다. input은 일반 문자열이거나, role(developer, system, user, assistant)과 content를 가진 항목의 배열입니다. 이 가이드에서 사용하는 그 밖의 문서화된 필드는 reasoning, max_output_tokens, stream, store, tools, tool_choice, previous_response_id, metadata입니다.
응답은 Responses 객체가 그대로 반환됩니다. 텍스트는 type: "output_text"인 output[].content[] 블록에, 호출 상태는 status에, 토큰 수는 usage.input_tokens, usage.output_tokens, usage.total_tokens에 있습니다.
OpenAI SDK를 사용하는 Python
SDK가 PoYo를 바라보도록 설정합니다.
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.poyo.ai/v1", api_key=os.environ["POYO_API_KEY"])
resp = client.responses.create(
model="gpt-6.2-sol",
input=[
{"role": "developer", "content": "You are a senior backend engineer."},
{"role": "user", "content": "Write a migration plan from Celery 4 to Celery 5."},
],
reasoning={"effort": "medium"},
max_output_tokens=8000,
)
print(resp.output_text)
print(resp.status, resp.usage)
resp.output_text는 모든 output_text 블록을 이어 붙여 주는 SDK 헬퍼입니다. 호출할 때마다 resp.usage를 로그로 남기세요. 아래 비용 섹션에서 이 값을 사용합니다.
기존 코드를 위한 Chat Completions
코드가 이미 chat.completions.create를 사용한다면 모델을 바꾸고 샘플링 필드를 제거하세요.
resp = client.chat.completions.create(
model="gpt-6.2-sol",
messages=[
{"role": "system", "content": "You are a senior backend engineer."},
{"role": "user", "content": "Explain the CAP theorem with one example per trade-off."},
],
max_tokens=4000,
)
print(resp.choices[0].message.content, resp.choices[0].finish_reason)
같은 요청을 cURL로 보내면 다음과 같습니다.
curl https://api.poyo.ai/v1/chat/completions \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6.2-sol",
"messages": [{"role": "user", "content": "Explain vector databases in one sentence."}],
"max_tokens": 1000
}'
PoYo의 Chat Completions 스키마는 model, messages(문자열 content, 역할은 system, user, assistant), max_tokens, stream, stop, n, 그리고 페널티 필드를 문서화하고 있습니다. tools는 문서화되어 있지 않고, OpenAI도 GPT-6.2 도구 호출에는 Responses가 필요하다고 밝히므로 에이전트는 /v1/responses에서 실행해야 합니다.
GPT-6.2 API에서 추론 강도 설정하기
OpenAI는 이 필드를 Responses에서는 reasoning.effort, Chat Completions에서는 reasoning_effort라고 부릅니다. PoYo의 Responses 레퍼런스는 reasoning(예: {"effort": "medium"})을 문서화하지만, Chat Completions 레퍼런스에는 아직 reasoning_effort가 없으므로 이 가이드에서는 Responses에서만 추론 강도를 설정합니다.
| 상황 | 설정 | 출처 |
|---|---|---|
| 신규 통합 | medium | OpenAI: "신규 통합에서는 medium으로 시작하세요." |
이전에 none 또는 minimal 사용 | low | OpenAI GPT-6.2 마이그레이션 노트 |
| 길거나 복잡한 작업 | 더 높은 수준 | OpenAI: 높은 추론 강도는 "최종 검사까지 끝까지 해내는 데 도움이 될 수 있습니다" |
none | 거부됨 | OpenAI 모델 페이지 |
OpenAI 추론 가이드는 가능한 값으로 low, medium, high, xhigh, max를 나열하지만, 모델에 따라 다르다고 밝힙니다. GPT-6.2 모델 페이지에는 허용되는 값 목록이 없으므로, medium보다 높은 수준을 하드코딩하기 전에 테스트 요청을 한 번 보내 보세요. 추론 토큰은 출력으로 과금되고 max_output_tokens에도 포함되며, OpenAI는 이를 usage.output_tokens_details.reasoning_tokens로 보고합니다.
GPT-6.2 API 응답 스트리밍
"stream": true를 지정하면 PoYo는 text/event-stream을 반환합니다. 각 data: 줄은 JSON이며 type이 이벤트 종류를 나타냅니다. 텍스트는 response.output_text.delta로 도착하고, response.completed가 usage를 포함한 최종 객체를 전달합니다. PoYo는 별도의 event: 줄을 보내지 않으며, 스트림은 data: [DONE]으로 끝납니다.
stream = client.responses.create(
model="gpt-6.2-sol",
input="Write a 100-word product introduction for a log search tool.",
reasoning={"effort": "low"},
max_output_tokens=2000,
stream=True,
store=False,
)
usage = None
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
elif event.type == "response.completed":
usage = event.response.usage
elif event.type == "response.failed":
raise RuntimeError(event.response)
print("\n", usage)
Chat Completions에서는 stream=True가 chat.completion.chunk 이벤트를 반환합니다. 텍스트는 choices[0].delta.content에 있고, 마지막 청크에 usage가 담깁니다.
이미지 입력
GPT-6.2는 텍스트와 함께 이미지를 받습니다. PoYo에서는 공개 URL이나 전체 Data URI(data:image/png;base64,...)를 담은 input_image 블록으로 Responses에 보냅니다. PoYo 문서는 텍스트를 이미지보다 앞에 두도록 권장합니다.
{
"model": "gpt-6.2-sol",
"input": [
{
"role": "user",
"content": [
{"type": "input_text", "text": "List every service in this architecture diagram that writes to the database."},
{"type": "input_image", "image_url": "https://example.com/diagram.png"}
]
}
],
"max_output_tokens": 3000
}
usage 읽기와 요청 비용 계산
PoYo의 100만 토큰당 가격: Sol은 입력 $1.60, 출력 $8, 캐시 읽기 $0.08, 캐시 쓰기 $2이고, Astra는 $6.40, $32, $0.32, $8입니다(1크레딧 = $0.005).
OpenAI 캐싱 가이드에 따르면 과금되는 캐시 읽기는 usage.input_tokens_details.cached_tokens에, 쓰기는 usage.input_tokens_details.cache_write_tokens에 보고됩니다. PoYo 스키마에는 input_tokens_details와 output_tokens_details가 있지만 그 키는 나와 있지 않으므로 방어적으로 읽으세요.
PRICES = { # PoYo USD per 1M tokens: input, output, cache read, cache write
"gpt-6.2-sol": (1.60, 8.00, 0.08, 2.00),
"gpt-6.2-astra": (6.40, 32.00, 0.32, 8.00),
}
def estimate_cost_usd(model: str, usage) -> float:
p_in, p_out, p_read, p_write = PRICES[model]
details = getattr(usage, "input_tokens_details", None)
cached = getattr(details, "cached_tokens", 0) or 0
written = getattr(details, "cache_write_tokens", 0) or 0
fresh = usage.input_tokens - cached - written
return (fresh * p_in + cached * p_read + written * p_write
+ usage.output_tokens * p_out) / 1_000_000
이 값은 추정치로 보고 PoYo 사용량 로그와 대조하세요. 여기 나온 가격은 모두 단기 컨텍스트 요금입니다. OpenAI는 입력이 272K 토큰을 넘으면 더 높은 요금을 부과하므로, 그만큼 큰 요청은 모델 페이지를 확인하세요. 계산 예시는 GPT-6.2 API 가격에 있습니다.
처리해야 할 오류
| HTTP | 원인 | 조치 |
|---|---|---|
| 400 | 잘못된 필드(validation_error, 세부 내용 포함) | 본문 수정. none 추론 강도나 문서화되지 않은 필드가 여기에 해당할 수 있음 |
| 401 | API 키 누락 또는 잘못된 키 | Authorization 헤더 확인 |
| 402 | 크레딧 부족 | 충전 후 재시도 |
| 404 | 알 수 없는 모델(model_not_found) | ID 확인: gpt-6.2-sol, gpt-6.2-astra |
| 429 | 속도 제한 | 잠시 기다린 후 재시도 |
| 500 / 502 / 503 | 서버 또는 업스트림 오류 | 지수 백오프로 재시도 |
PoYo 문서에 따르면 LLM 엔드포인트에는 현재 속도 제한이 없지만, 그래도 429는 처리해 두세요. OpenAI SDK에서는 openai.APIStatusError를 잡아 status_code로 분기합니다. 재시도는 5xx와 429에만 하세요. 400은 본문을 바꾸기 전까지 계속 실패합니다. 전체 응답 본문은 PoYo 오류 코드에 있습니다.
배포 전 체크리스트
POYO_API_KEY는 서버에만 두고, 브라우저나 모바일 코드에 절대 포함하지 마세요.- 공용 헬퍼 함수를 포함해 GPT-6.2로 가는 모든 요청 경로에서
temperature와top_p를 제거하세요. max_output_tokens(또는max_tokens)를 항상 설정하고, 그 상한 안에 추론 토큰을 위한 여유를 남기세요.status/finish_reason과usage블록 전체를 자체 요청 ID와 함께 로그로 남겨, 잘린 답변과 비용 급증이 보이도록 하세요.- 길고 고정된 컨텍스트는 첫
developer메시지에, 바뀌는 질문은 맨 뒤에 두어 프롬프트 캐싱이 적용될 여지를 만드세요. - 모델 ID를 설정 파일에 고정해, 배포 없이
gpt-6.2-sol과gpt-6.2-astra를 전환할 수 있게 하세요.
도구, 도구 호출 스트리밍, 긴 에이전트 세션의 캐싱은 코딩 에이전트를 위한 GPT-6.2 API에서 이어집니다.
자주 묻는 질문
Python에서 GPT-6.2 API를 어떻게 호출하나요?
OpenAI SDK에 base_url="https://api.poyo.ai/v1"과 PoYo 키를 설정하고, client.responses.create에서 model="gpt-6.2-sol" 또는 "gpt-6.2-astra"를 지정하세요.
GPT-6.2 API는 스트리밍을 지원하나요?
예, 두 엔드포인트 모두 지원합니다. stream: true를 설정하면 Responses는 response.output_text.delta 같은 타입이 지정된 이벤트를, Chat Completions는 chat.completion.chunk 이벤트를 보냅니다. 둘 다 data: [DONE]으로 끝납니다.
GPT-6.2 API의 추론 강도는 어떻게 설정하나요?
/v1/responses에 "reasoning": {"effort": "medium"}을 보내세요. OpenAI는 medium으로 시작할 것을 권장하며 none은 거부합니다.
GPT-6.2 API 요청이 temperature 때문에 실패하는 이유는 무엇인가요?
OpenAI는 GPT-6.2에서 temperature와 top_p를 생략하라고 안내합니다. 이 필드를 제거하고 출력 길이는 max_output_tokens 또는 max_tokens로 제어하세요.
GPT-6.2 API에 이미지를 어떻게 보내나요?
/v1/responses를 사용해 input_text 블록 뒤에 input_image 블록(URL 또는 Data URI)을 넣으세요. PoYo의 Chat Completions 스키마는 문자열 content만 문서화하고 있습니다.