GPT-6 Astra API 사용 방법: 프로젝트 권한 확인부터 첫 응답까지

GPT-6 Astra API는 이미 제공 중입니다. 2026년 9월 5일 확인한 OpenAI 공식 안내는 API 출시를 명시합니다. 이제 애플리케이션에서 사용할 API 프로젝트로 gpt-6-astra 요청을 보낼 수 있는지 확인하면 됩니다.

ChatGPT에서 Astra를 선택할 수 있다는 사실만으로 이 조건이 충족되지는 않습니다. API 키가 속한 조직과 프로젝트의 권한을 확인하고, 유효한 요청을 보낸 다음 실제 응답 내용을 읽어야 합니다. 아래 예제는 공식 API를 직접 사용하는 개발자를 위한 코드이며, 특정 계정에서의 호출 성공이나 무료 사용량을 보장하지 않습니다.

시작하기 전에 확인할 계정과 결제 조건

먼저 요청이 어느 서비스로 전송되는지 확인하세요. 이 글은 https://api.openai.com/v1을 사용하는 OpenAI 공식 API 기준입니다. 다른 서비스의 base_url과 키를 쓰고 있다면 모델 이름, 지원 기능, 요금, 문의할 곳도 해당 서비스 기준으로 확인해야 합니다. OpenAI 공식 API에서 통하는 모델 ID가 다른 서비스에서도 같다고 가정하면 안 됩니다.

공식 API를 사용한다면 API Platform에서 사용할 조직과 프로젝트를 선택하고 다음을 확인합니다.

• API 키: 해당 프로젝트에 속한 키인지, 폐기되거나 비활성화되지 않았는지, 호출할 API에 필요한 권한이 있는지 확인합니다.
• 결제와 사용 한도: API 결제 설정, 크레딧 잔액, 조직과 프로젝트의 지출 한도를 확인합니다. ChatGPT 구독을 API 결제 설정 대신으로 생각하면 안 됩니다.
• 모델 사용 조건: Astra 모델 문서는 Free 사용 등급을 지원하지 않는 것으로 표시합니다. 유료 결제를 설정했다는 사실과 해당 프로젝트에서 Astra 요청이 허용된다는 사실은 각각 확인해야 합니다.
• 지원 국가: 대한민국은 공식 API 지원 국가 목록에 포함됩니다. 해외에서 이용하거나 해외 서버에서 요청한다면 실제 이용 환경에 적용되는 조건도 확인합니다.

OpenAI의 모델 사용 권한 안내는 API 키 인증의 권한이 키에 연결된 API 조직·프로젝트를 따른다고 설명합니다. ChatGPT 워크스페이스에서 Astra를 활성화해도 API 권한이 생기지는 않습니다. 같은 문서의 초기 Enterprise 도입 조건인 Daybreak를 모든 API 개발자가 거쳐야 하는 공통 신청 절차로 해석할 필요도 없습니다.

최초 확인에는 사용할 수 있는 프로젝트 하나와 그 프로젝트의 키 하나면 충분합니다. 여러 조직의 키나 다른 서비스의 주소를 섞어 바꾸면 어떤 설정 때문에 성공하거나 실패했는지 추적하기 어려워집니다.

Python으로 첫 Responses 요청 보내기

Astra의 공식 모델 ID는 gpt-6-astra입니다. 모델 사용 가이드에 따르면 Responses API와 Chat Completions를 지원하지만, Astra의 도구 호출에는 Responses API가 필요합니다. 처음부터 Responses로 연결하면 이후 기능을 추가할 때 요청 방식을 다시 바꿀 일을 줄일 수 있습니다.

아래 코드는 일반 텍스트 응답을 한 번 요청하고, 응답 ID·모델·처리 상태·사용량을 출력합니다. 예제의 max_output_tokens=4096은 첫 확인용으로 정한 출력 한도이며, 모든 요청이 이 한도 안에서 완료된다는 뜻은 아닙니다. 실행하면 API 사용료가 발생할 수 있습니다. 비용을 먼저 예상해야 한다면 GPT-6 Astra API 가격과 계산법을 확인하세요.

SDK 설치와 키 설정

Python이 설치된 터미널에서 공식 SDK를 설치하거나 업데이트합니다. SDK 설치와 환경 변수 방식은 OpenAI 시작 가이드를 따릅니다.

bash
python -m pip install --upgrade openai

macOS·Linux 터미널에서는 다음과 같이 설정합니다. YOUR_API_KEY를 자신이 생성한 키로 바꾸세요.

bash
export OPENAI_API_KEY="YOUR_API_KEY"

Windows PowerShell에서 현재 세션에 설정하려면 다음을 사용합니다.

powershell
$env:OPENAI_API_KEY="YOUR_API_KEY"

API 키는 서버 측 환경 변수나 비밀 관리 도구에 보관하세요. 브라우저에서 내려받을 수 있는 JavaScript, 공개 저장소, 오류 화면에 넣으면 안 됩니다. 이미 키를 설정했는데도 인증에 실패한다면 현재 실행 중인 터미널이나 서버 프로세스가 그 값을 읽고 있는지부터 확인합니다.

요청과 오류 정보를 함께 확인하는 코드

다음 내용을 astra_access.py로 저장합니다. JSON 키와 SDK 인수는 그대로 두고, input의 요청 문장만 필요에 맞게 바꾸면 됩니다.

python
import os
import sys

import openai
from openai import OpenAI

if not os.environ.get("OPENAI_API_KEY"):
    sys.exit("OPENAI_API_KEY 환경 변수를 먼저 설정하세요.")

client = OpenAI(
    base_url="https://api.openai.com/v1",
    max_retries=0,
    timeout=120.0,
)

try:
    response = client.responses.create(
        model="gpt-6-astra",
        reasoning={"effort": "low"},
        input="API 연결 확인용입니다. 한국어로 짧은 인사 한 문장을 써 주세요.",
        max_output_tokens=4096,
    )
except openai.APIStatusError as exc:
    try:
        body = exc.response.json()
    except ValueError:
        body = {}
    error = body.get("error", {}) if isinstance(body, dict) else {}
    if not isinstance(error, dict):
        error = {}
    print({
        "http_status": exc.status_code,
        "request_id": exc.request_id,
        "error.code": error.get("code"),
        "error.type": error.get("type"),
        "error.param": error.get("param"),
        "error.message": error.get("message"),
    })
    sys.exit(1)
except openai.APIConnectionError as exc:
    print("API 연결 또는 시간 초과 문제:", type(exc).__name__)
    sys.exit(1)

print({
    "id": response.id,
    "model": response.model,
    "status": response.status,
    "incomplete_details": (
        response.incomplete_details.model_dump()
        if response.incomplete_details else None
    ),
    "usage": response.usage.model_dump() if response.usage else None,
})

text = response.output_text
if response.status == "completed" and text.strip():
    print("텍스트 응답 확인:", text)
else:
    print("응답을 추가로 확인해야 합니다.")
    print("output:", [item.model_dump() for item in response.output])
    print("error:", response.error.model_dump() if response.error else None)

저장한 파일을 실행합니다.

bash
python astra_access.py

max_retries=0은 최초 오류를 그대로 확인하기 위한 설정입니다. 자동으로 재시도하지 않으므로, 같은 요청을 여러 번 반복하기 전에 아래 오류 해석부터 확인할 수 있습니다. timeout=120.0은 이 예제의 대기 설정이며 Astra의 응답 시간 보장이 아닙니다. 실패 정보는 로컬 진단용으로 보관하고, 외부에 공유하기 전에 입력 내용이나 계정 정보가 섞여 있지 않은지 확인하세요.

어떤 응답이면 연결을 확인했다고 볼 수 있나요?

이 예제에서는 공식 API 주소와 의도한 프로젝트의 키를 사용했는지 먼저 확인합니다. 오류 없이 응답을 받았다면 model 값을 확인하고, status가 completed이며 읽을 수 있는 텍스트가 있는지 봅니다. 이 조건을 충족하면 해당 프로젝트에서 첫 텍스트 응답을 확인한 것입니다. 모델이 본문에서 “저는 Astra입니다”라고 말하는 것은 모델 식별 근거가 아닙니다. 요청 설정과 응답의 model 값을 확인하세요.

이 결과가 증명하는 범위는 해당 시점에 그 프로젝트로 해당 요청을 처리했다는 것까지입니다. 이후 대량 요청의 처리량이나 도구 실행, 파일 처리, 다른 프로젝트의 사용 권한까지 검증한 것은 아닙니다.

응답은 왔지만 텍스트가 비어 있을 때

HTTP 요청이 성공했다고 해서 원하는 문장이 반드시 완성된 것은 아닙니다. Astra는 추론 모델이며 max_output_tokens에는 화면에 보이는 답변뿐 아니라 추론에 쓰인 토큰도 포함됩니다. 한도에 도달하면 status가 incomplete, incomplete_details.reason이 max_output_tokens로 반환될 수 있습니다. 이때 보이는 텍스트가 없어도 입력과 추론에 대한 비용이 발생할 수 있습니다. 추론 모델의 출력 한도 설명

이 경우에는 키를 새로 만들기보다 usage와 incomplete_details를 읽으세요. 입력을 단순화하거나, 허용할 비용을 고려해 출력 한도를 늘린 뒤 다시 요청하는 것이 맞습니다. incomplete의 원인이 항상 토큰 한도인 것은 아니므로 실제 reason을 먼저 확인합니다. 상태가 completed인데도 텍스트가 없다면 output의 항목 유형과 내용을 확인합니다. 거절 응답 등 일반 텍스트와 다른 결과를 빈 문자열 하나로 뭉뚱그려 처리하면 원인을 놓칠 수 있습니다.

REST JSON에서 텍스트를 읽는 위치

위 Python 코드의 response.output_text는 SDK가 텍스트를 모아 주는 편의 속성입니다. REST 응답을 직접 파싱할 때는 output 배열 안의 메시지와 그 메시지의 content를 확인해야 합니다. 배열에는 추론 항목이나 도구 호출도 들어올 수 있으므로 output[0].content[0].text라고 고정해서 접근하면 안 됩니다. 공식 텍스트 생성 가이드

이미 받은 REST 응답 JSON을 payload라는 사전에 담았다면, 텍스트를 모으는 부분은 다음과 같이 작성할 수 있습니다. 이 코드는 새 API 요청을 보내지 않습니다.

python
text = "".join(
    part.get("text", "")
    for item in payload.get("output", [])
    if item.get("type") == "message"
    for part in item.get("content", [])
    if part.get("type") == "output_text"
)

이렇게 문자열을 추출한 뒤에도 status, incomplete_details, 거절이나 도구 호출 항목을 별도로 처리해야 합니다. 특히 도구를 추가한 애플리케이션에서는 텍스트가 없다는 이유만으로 실패라고 판정할 수 없습니다.

호출에 실패했을 때 바꿔야 할 설정

첫 요청의 오류는 HTTP 상태와 error.code, error.param, error.message를 함께 읽어야 합니다. 특히 429는 크레딧 부족과 요청 속도 초과를 모두 나타낼 수 있습니다. 아래 구분은 OpenAI 오류 코드 문서를 기준으로 합니다.

잔액과 지출 한도 오류에서는 error.type이 넓은 범주의 insufficient_quota로 표시될 수 있습니다. 따라서 그 값만 보고 전부 충전 문제라고 판단하지 말고 error.code를 확인하세요. 속도 제한을 반복해서 만난다면 OpenAI API 요청 한도와 429 처리 방법에서 대기·동시성 설정을 이어서 확인할 수 있습니다.

기존 모델에서 이름만 바꿨다면

Astra 요청에 이전 모델의 설정이 남아 있으면 계정에 문제가 없어도 요청이 거절될 수 있습니다. 공식 마이그레이션 안내에 따라 다음을 확인합니다.

• reasoning.effort에 none이나 minimal을 넣었다면 low부터 시작합니다. Astra가 지원하는 값은 low, medium, high, xhigh, max입니다.
• temperature, top_p, top_logprobs를 제거합니다. Chat Completions에서는 logprobs도 제거하고, Responses에서는 include 안의 message.output_text.logprobs를 제거합니다.
• 도구 호출이 필요하면 Responses를 사용합니다. Chat Completions에서 reasoning_effort를 사용하던 코드를 Responses로 옮길 때는 reasoning={"effort": "low"}처럼 해당 API의 구조로 바꿉니다.
• EU 데이터 레지던시가 설정된 프로젝트에서는 Astra의 Fast 처리가 지원되지 않습니다. 이 경우 service_tier의 fast·priority 대신 Standard를 사용합니다. 별도로 프로젝트가 허용한 처리 등급도 확인해야 합니다.

주소·키·인수 문제를 수정했는데도 같은 오류가 지속되면, 요청 시각과 시간대, 응답의 요청 ID, 모델 ID, 오류 코드 및 메시지를 함께 보관하세요. 이 정보가 있어야 조직 관리자나 지원팀이 해당 요청을 찾을 수 있습니다. 비밀 키 자체를 보내지는 마세요.

첫 텍스트 응답을 확인한 뒤에는 실제 애플리케이션이 필요로 하는 기능을 하나씩 추가하면 됩니다. Astra가 화면을 읽고 조작하도록 만들려는 경우에는 텍스트 호출 다음으로 도구 실행과 결과 반환을 구현해야 하므로 GPT-6 Astra 컴퓨터 사용 API 가이드로 이어서 진행하세요.