공식 OpenAI 인증으로 Astra API 설정하기

먼저 제공업체와 결제 계정을 확인하세요

자체 OpenAI Platform 키를 사용해 OpenAI API에서 gpt-6-astra를 사용하세요. 애플리케이션에서는 아래의 Responses 예시부터 시작합니다. 로컬 코딩 작업에서는 Codex CLI 로그인 및 모델 선택 명령을 사용하세요. 두 경로 모두 Platform 계정을 사용하며 해당 OpenAI 요금에 따라 API 비용이 발생합니다.

요청을 실행하기 전에 Platform 프로젝트의 소유자, 해당 키의 모델 접근 권한, 적용되는 결제 제어를 확인하세요. ChatGPT 또는 Codex에 모델이 표시된다고 해서 모든 API 프로젝트에 접근할 수 있는 것은 아닙니다. 작업 기록에서는 구독 로그인과 API 키 로그인을 분리해 적으세요. 이 구분은 나중에 제한 원인을 진단하거나 청구 금액을 대조할 때 필수입니다.

신뢰할 수 있는 환경에서 키와 클라이언트를 준비하세요

OpenAI 대시보드에서 API 키를 만들고 비공개 환경 또는 시크릿 매니저를 통해 OPENAI_API_KEY로 제공합니다. 공식 SDK가 이 변수를 읽습니다. 키를 브라우저 JavaScript, 공개 저장소, 스크린샷 또는 공유 터미널 기록에 절대 포함하지 마세요. 자격 증명을 다루는 동안 셸 추적도 피하세요.

아래 JavaScript 예시를 사용하려면 프로젝트에서 npm install openai로 공식 openai 패키지를 설치하세요. 설치된 버전을 lockfile에 기록합니다. 명시적인 baseURL은 상속된 사용자 지정 엔드포인트가 아니라 OpenAI를 선택합니다. 기존 에이전트 설정도 검토하세요. 두 서비스가 모두 Authorization 헤더를 받는다는 이유만으로 제공업체 재정의와 다른 서비스의 자격 증명이 호환되는 것은 아닙니다.

Responses 요청을 보내고 답변을 읽으세요

다음 코드로 astra-example.mjs를 만든 다음 node astra-example.mjs를 실행하세요. 프롬프트는 짧은 체크리스트를 요청하므로 더 큰 워크플로에 연결하기 전에 반환된 답변을 확인할 수 있습니다. 첫 요청에서는 자동 SDK 재시도를 비활성화해 연결 또는 계정 오류를 더 쉽게 진단하도록 합니다.

상태가 completed이면 response.output_text에 SDK가 결합한 텍스트 출력이 들어 있습니다. 다른 프로그램이 소비하거나 파일로 리디렉션할 수 있도록 표준 출력에 인쇄하세요. 답변과 분리할 수 있도록 응답 메타데이터는 표준 오류에 보냅니다. 응답이 불완전하면 incomplete_details와 usage를 보존하고 0이 아닌 종료 코드를 반환하세요.

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://api.openai.com/v1',
  maxRetries: 0,
})
const response = await client.responses.create({
  model: 'gpt-6-astra',
  input: 'List three checks for a small code change.',
})
console.error(JSON.stringify({
  id: response.id,
  model: response.model,
  status: response.status,
  usage: response.usage,
  incomplete_details: response.incomplete_details,
}))
if (response.status === 'completed') {
  console.log(response.output_text)
} else {
  process.exitCode = 1
}

로컬 Codex에서 API 키 인증을 선택하세요

OpenAI는 로컬 Codex 작업에서 API 키 로그인을 지원한다고 문서화하고 있습니다. CLI에서 자격 증명을 바꾸기 전에 codex login status를 확인하세요. 아래의 표준 입력 명령은 시크릿을 명령 인수에 붙여넣지 않도록 합니다. 로그인 후 활성 인증 방식을 다시 확인하고, CLI 모델 플래그로 정확한 모델을 선택하세요.

마지막 명령은 Astra를 선택한 대화형 세션을 엽니다. 에이전트가 올바른 파일과 저장소 지침을 읽을 수 있도록 프로젝트 디렉터리에서 시작하세요. 기존 제공업체 재정의를 검토하고 활성 계정을 확인하세요. API 키 모드는 로컬 작업을 지원하며, Codex cloud는 ChatGPT 인증이 필요합니다. 로컬에서 계속하려는 cloud 작업이라면 먼저 작업 파일과 남은 작업의 짧은 요약을 로컬 프로젝트로 가져오세요.

codex login status
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status
codex --model gpt-6-astra

기능을 클라이언트 경로에 맞추세요

Astra는 Responses와 Chat Completions를 지원하지만 도구 호출에는 Responses가 필요합니다. 함수 또는 사용자 지정 도구를 실행하는 에이전트에는 Responses를 사용하세요. chat choices를 읽도록 작성된 클라이언트는 URL만 바꿔서 Responses 출력을 파싱할 수 없으며, 텍스트 전용 스모크 테스트는 도구 루프를 실행하지 않습니다.

애플리케이션에서 작은 예시를 사용해 기능을 한 번에 하나씩 추가하세요. 도구의 경우 인수를 검증하고 애플리케이션에서 함수를 실행한 뒤 일치하는 call_id와 함께 Responses를 통해 결과를 반환하세요. 구조화된 출력은 스키마를 검증하고 불완전한 응답을 처리하세요. 스트리밍은 텍스트뿐 아니라 완료 및 취소 이벤트도 처리하세요. 이러한 기능을 추가하는 동안 단순 텍스트 요청을 진단 경로로 유지하세요.

접근, 요청 제한, 완료 실패를 분리해 진단하세요

재시도하기 전에 HTTP 상태와 구조화된 오류 필드를 확인하세요. OpenAI 오류 가이드는 잘못된 인증, 소진된 크레딧, 적용된 지출 한도, 요청 속도 압박을 구분합니다. 특히 429 응답만으로 해결책을 선택해서는 안 됩니다. error.code와 관련 계정 설정을 확인하세요.

일시적인 요청 제한이라면 Retry-After가 있을 때 이를 준수하고 제한된 횟수로 재시도하세요. 결제 또는 지출 한도 오류는 반복 요청이 아니라 계정 결정이 필요한 문제입니다. incomplete로 표시된 Responses 결과는 또 다른 조건이며 이미 토큰을 소비했을 수도 있습니다. 비식별화한 오류 정보와 사용량을 보존하고, 타임아웃이나 누락된 영수증을 성공 또는 무료 시도로 처리하지 마세요.

제공업체 제공 여부와 근거: 2026년 9월 5일

OpenAI는 단계적 출시 방식으로 GPT-6 Astra를 발표했으며, 모델 레퍼런스에는 공식 API가 문서화되어 있습니다. 이 예시들은 해당 출처를 따르며, 이 가이드를 위해 유료 요청이나 Codex 인증 전환을 실행하지 않았습니다. 2026년 9월 5일 공개 APIsRouter 카탈로그 확인에서는 HTTP 200, success: true, 34개 모델이 반환되었고 Astra 또는 GPT-6 항목은 없었습니다.

위에 제시한 공식 엔드포인트에서는 OpenAI 자격 증명만 사용하세요. APIsRouter의 자체 제공 항목은 실시간 카탈로그에서 확인하세요. 이후 Astra가 목록에 추가되더라도 애플리케이션에서 사용하기 전에 정확한 모델 ID, 가격, 필요한 클라이언트 기능을 확인해야 합니다.

응답을 유용한 로컬 워크플로에 연결하세요

함수를 설명하고 테스트를 제안하는 것처럼 구체적인 결과가 있는 로컬 작업 하나를 선택하세요. 에이전트에 관련 파일 경로, 기대 동작, 테스트 명령을 제공하세요. 코드 변경 후에는 diff를 검토하고 범위가 좁은 테스트를 실행하세요. 수정 사항을 쉽게 비교할 수 있도록 원래 입력과 반환된 답변을 함께 보존하세요.

애플리케이션에서는 완료된 텍스트를 검토 화면이나 문서 파이프라인으로 전달하세요. 다음 단계가 기계 판독 가능한 데이터를 기대한다면 구조화된 출력을 사용하고 저장하기 전에 필수 필드를 검증하세요. 요청 ID와 사용량을 작업 정보와 함께 보존하고 재시도 정책에 상한을 설정하세요. 기본 입력, 응답 처리, 완료 확인이 함께 작동한 뒤 워크플로를 확장하세요.

자주 묻는 질문