GPT-6 Astra Responses API로 제대로 쓰기

이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.

 

GPT-6 Astra를 잘 쓴다는 말이 막연해서, 이번에는 Responses API로 코드 변경 계획 하나를 요청하고 응답 파일의 상태·모델·사용량을 터미널에서 확인하는 데까지 정리했다. 어려운 작업일수록 프롬프트를 길게 쓰는 것보다 완료 조건과 허용 범위를 먼저 고정하는 편이 결과를 확인하기 쉽다.

공식 표기는 GPT-6 Astra, API 모델 ID는 gpt-6-astra다. OpenAI는 이 모델을 복잡한 추론, 코딩, 컴퓨터 사용, 연구, 문서 작업용으로 안내한다. 모델 자체 사양과 현재 요금은 GPT-6 Astra 모델 페이지, 모델별 권장 설정은 공식 모델 가이드에서 확인할 수 있다.

준비할 것

아래 예제는 macOS·Linux·WSL의 Bash/Zsh에서 실행한다. Windows PowerShell에서는 따옴표와 환경 변수 문법을 바꿔야 한다.

항목	요구 사항
계정	GPT-6 Astra를 사용할 수 있고 결제가 설정된 OpenAI API 프로젝트
인증	현재 셸의 OPENAI_API_KEY 환경 변수
명령	curl, jq
비용	2026년 9월 6일 공식 표기 기준 100만 토큰당 입력 $10, 캐시 입력 $1, 출력 $50

무료 API 티어는 GPT-6 Astra를 지원하지 않는다. 또 272K 입력 토큰을 넘는 프롬프트에는 별도 배율이 적용되므로, 큰 저장소를 통째로 붙이기 전에 모델 페이지의 최신 가격을 다시 확인해야 한다. API 키 값은 명령 기록이나 파일에 직접 적지 않는다.

먼저 도구와 환경 변수만 확인한다.

입력

command -v curl
command -v jq
test -n "$OPENAI_API_KEY" && echo 'OPENAI_API_KEY configured'

출력 예시(경로는 환경마다 다름)

/usr/bin/curl
/opt/homebrew/bin/jq
OPENAI_API_KEY configured

출력의 의미

세 줄이 모두 나오면 HTTP 호출과 JSON 확인에 필요한 준비가 됐다. 마지막 명령은 키의 존재 여부만 확인하며 키 자체는 출력하지 않는다. 이 단계는 시스템이나 API 데이터를 바꾸지 않는다.

GPT-6 Astra 요청을 작게 고정하기

공식 가이드는 GPT-6 Astra를 Responses API에서 model: gpt-6-astra로 호출하라고 안내한다. 특히 도구 호출을 붙일 계획이라면 Responses API를 써야 한다. 첫 요청은 low 추론으로 시작하고, 실제 평가에서 부족할 때만 높이는 편이 비용과 지연을 비교하기 쉽다. Astra는 low, medium, high, xhigh, max를 지원하며 none은 지원하지 않는다.

요청에는 역할 설명보다 다음 네 가지를 짧게 넣었다.

• 만들어야 할 결과: 변경 계획
• 지켜야 할 범위: 파일 수정 금지
• 근거 규칙: 제공된 사실만 사용
• 출력 형식: 세 항목과 300자 제한

프로젝트마다 이런 규칙이 반복된다면 별도 지침 파일로 관리하는 것도 좋다. 이 블로그의 Gemini CLI 설치와 GEMINI.md 프로젝트 설정 글도 프로젝트 규칙을 파일로 고정하고 실제 로딩 여부를 확인하는 흐름을 다룬다.

입력

jq -n '{
  model: "gpt-6-astra",
  reasoning: {effort: "low"},
  text: {verbosity: "low"},
  instructions: "한국어로 답한다. 제공된 사실만 사용한다.",
  input: "목표: 결제 API의 중복 청구 방지 변경 계획을 작성한다. 범위: 파일은 수정하지 않는다. 완료 조건: 원인 가설, 변경 파일, 검증 명령을 각각 한 항목으로 쓰고 300자 이내로 끝낸다.",
  max_output_tokens: 800,
  store: false
}' > request.json

jq '{model, reasoning, text, max_output_tokens, store}' request.json

출력 예시

{
  "model": "gpt-6-astra",
  "reasoning": { "effort": "low" },
  "text": { "verbosity": "low" },
  "max_output_tokens": 800,
  "store": false
}

출력의 의미

model과 reasoning.effort가 의도한 값이면 호출 조건이 고정된 것이다. text.verbosity는 보이는 답의 길이를 낮추고, max_output_tokens는 추론 토큰을 포함한 전체 생성 상한이다. store: false는 이 응답을 기본 저장 대상으로 남기지 않겠다는 설정이다. 이 명령은 현재 폴더에 request.json 하나를 만든다.

이 그림처럼 입력 계약, 추론 강도, 검증 결과를 따로 보면 어디를 고쳐야 할지 빨리 찾을 수 있다. 답이 길다는 문제는 verbosity, 어려운 제약을 놓치는 문제는 프롬프트와 reasoning.effort, 성공 여부 확인은 응답의 status와 테스트 명령에서 다룬다.

Responses API 호출하고 성공 줄 찾기

Responses API 레퍼런스는 텍스트·이미지 입력, JSON 출력, 도구 호출과 previous_response_id 기반 후속 요청을 지원한다고 설명한다. 여기서는 가장 작은 텍스트 호출만 보낸다. 아래 출력은 공식 응답 구조에 맞춰 줄인 문서 기반 예시이며, 실제 실행을 주장하는 값이 아니다.

입력

curl -sS https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json \
  --output response.json

jq '{id, status, model, error, usage}' response.json
jq -r '.output[] | select(.type == "message") | .content[] | select(.type == "output_text") | .text' response.json

출력 예시(ID와 토큰 수는 매번 달라짐)

{
  "id": "resp_...",
  "status": "completed",
  "model": "gpt-6-astra",
  "error": null,
  "usage": {
    "input_tokens": 92,
    "output_tokens": 148,
    "total_tokens": 240
  }
}
원인 가설: 멱등성 키가 재시도 요청 사이에 유지되지 않는다.
변경 파일: 결제 요청 생성부와 재시도 정책을 확인한다.
검증 명령: 동일 키로 통합 테스트를 두 번 실행해 청구가 한 건인지 확인한다.

출력의 의미

status가 completed, model이 gpt-6-astra, error가 null이면 요청은 정상 완료됐다. 토큰 수와 답 내용은 입력과 계정 설정에 따라 달라진다. response.json에는 전체 응답이 남고, 두 번째 jq 명령은 배열의 위치를 가정하지 않고 output_text만 골라낸다.

추론 강도는 한 단계씩 비교하기

처음부터 max를 쓰면 결과 차이가 프롬프트 때문인지 추론량 때문인지 판단하기 어렵다. 같은 요청과 완료 조건을 유지한 채 low와 high처럼 한 변수만 바꾸고, 실제 사례 여러 개에서 정확도·지연·토큰을 함께 기록한다.

입력

jq '.reasoning.effort = "high"' request.json > request-high.json
jq '{model, reasoning, text}' request-high.json

출력 예시

{
  "model": "gpt-6-astra",
  "reasoning": { "effort": "high" },
  "text": { "verbosity": "low" }
}

출력의 의미

추론 강도만 high로 바뀌었고 출력 길이 설정은 그대로다. 이 파일을 같은 API 명령에 넣어 비교하면 된다. 높은 추론 강도가 항상 더 좋은 것은 아니므로, 복잡한 코드 분석이나 다단계 도구 작업에서 측정 가능한 개선이 있을 때 올리는 것이 안전하다.

오류 해결

401 invalid_api_key

실패 출력 예시

{
  "error": {
    "message": "Incorrect API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

진단 입력

test -n "$OPENAI_API_KEY" && printf 'key length: ' && printf '%s' "$OPENAI_API_KEY" | wc -c

출력 예시

key length:       164

출력의 의미와 해결

숫자가 나오면 현재 셸에 값은 있지만 유효하다는 뜻은 아니다. 키를 화면에 출력하지 말고 OpenAI API 프로젝트에서 활성 키인지 확인한 뒤 새 터미널에 다시 설정한다. 아무것도 나오지 않으면 현재 셸에 환경 변수가 없는 상태다.

400 unsupported_parameter

GPT-6 Astra 마이그레이션 가이드는 temperature, top_p, top_logprobs를 제거하라고 안내한다.

실패 출력 예시

Unsupported parameter: 'temperature' is not supported with this model.

진단 입력

jq '{temperature, top_p, top_logprobs, reasoning}' request.json

출력 예시

{
  "temperature": null,
  "top_p": null,
  "top_logprobs": null,
  "reasoning": { "effort": "low" }
}

출력의 의미와 해결

세 항목이 null이면 현재 파일에는 지원하지 않는 샘플링 옵션이 없다. 값이 보이면 jq 'del(.temperature, .top_p, .top_logprobs)' request.json > request-fixed.json으로 제거하고 다시 호출한다. reasoning.effort에 none을 넣었다면 low 이상으로 바꾼다.

429 rate_limit_exceeded 또는 insufficient_quota

진단 입력

jq '.error | {type, code, message}' response.json

출력 예시

{
  "type": "insufficient_quota",
  "code": "insufficient_quota",
  "message": "You exceeded your current quota."
}

출력의 의미와 해결

insufficient_quota는 재시도만으로 해결되지 않는다. 프로젝트의 결제 상태와 사용 한도를 확인한다. rate_limit_exceeded라면 현재 사용 등급의 RPM·TPM 한도를 확인하고 요청 빈도나 입력 크기를 줄인 뒤 지수 백오프로 재시도한다.

마지막으로 저장된 응답이 완료 상태이며 정확한 모델에서 나왔는지 짧게 확인한다.

입력

jq -e '.status == "completed" and .model == "gpt-6-astra" and .error == null' response.json >/dev/null \
  && echo 'GPT-6 Astra response verified'

출력 예시

GPT-6 Astra response verified

출력의 의미

이 한 줄이 나오면 API 처리 완료, 모델 ID 일치, 오류 없음까지 확인한 것이다. 이제 실제 업무에서는 마지막 조건에 테스트 결과나 JSON 스키마 검증을 더하면 된다.