OmniaKey에서 GPT-6 Astra 사용하기

이 튜토리얼은 새 OmniaKey 계정에서 첫 GPT-6 Astra 요청이 성공할 때까지 안내합니다. 서버 측 API 호출과 Codex CLI 설정을 다룹니다. OmniaKey API 키는 ChatGPT 구독이 아니므로 ChatGPT 웹사이트에 입력해 사용할 수 없습니다.

OpenAI의 현재 Astra 가이드는 Responses API로 시작합니다. 일반 텍스트에는 Chat Completions도 사용할 수 있지만 Astra 도구 호출에는 Responses가 필요합니다. 아래 예시는 이 경계를 지키며, 키를 소스 코드에 넣지 않고 환경 변수에서 읽습니다.

시작하기 전에

범위가 제한된 API 키 만들기

OmniaKey에 로그인하고 API 키 페이지를 여세요. 이번 연동용 키를 따로 만들고 테스트에 맞는 한도와 만료일을 설정한 뒤 키가 표시되면 복사합니다.

계정에도 사용 가능한 잔액이 있어야 합니다. 키를 만들었다는 사실은 자격 증명이 존재한다는 뜻일 뿐, 요청 비용을 지불할 수 있다는 뜻은 아닙니다.

키를 비밀번호처럼 다루세요. Git에 커밋하거나 브라우저 애플리케이션에 넣거나 스크린샷 또는 채팅에 포함하지 마세요.

환경 변수에 키 저장하기

macOS 또는 Linux에서는 다음을 실행합니다.

export OMNIAKEY_API_KEY="your-omniakey-api-key"

PowerShell에서는 다음과 같습니다.

$env:OMNIAKEY_API_KEY="your-omniakey-api-key"

아래 SDK와 Codex 예시는 모두 이 변수를 읽습니다.

첫 Responses API 요청 보내기

터미널에서 다음 요청을 실행하세요.

curl https://api.omniakey.com/v1/responses \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "reasoning": {"effort": "medium"},
    "input": "이 마이그레이션 계획을 검토하고 가장 큰 위험 두 가지와 각각의 인수 테스트 하나를 반환하세요."
  }'

성공한 응답에는 output 배열, 생성된 텍스트, 토큰 사용량이 포함됩니다. 이 첫 호출 하나로 Base URL, 키, 잔액, 모델 권한, 모델 ID, Responses 경로를 함께 확인할 수 있습니다.

성공한 뒤 사용량 대시보드를 열어 기록된 모델이 gpt-6-astra인지 확인하세요. 화면에 보이는 텍스트 길이만으로 비용을 추정하지 말고 실제 입력, 캐시 입력, 추론, 출력 사용량을 검토합니다.

Python에서 Astra 호출하기

OpenAI 공식 Python SDK를 설치하거나 업데이트합니다.

python -m pip install --upgrade openai

astra_example.py를 만드세요.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OMNIAKEY_API_KEY"],
    base_url="https://api.omniakey.com/v1",
)

response = client.responses.create(
    model="gpt-6-astra",
    reasoning={"effort": "medium"},
    input="이 장애 보고서를 설명하고 다음에 할 가장 유용한 점검 세 가지를 나열하세요.",
)

print(response.output_text)

실행합니다.

python astra_example.py

response.output_text는 생성 텍스트를 꺼내는 SDK 편의 필드입니다. 사용량, 상태, 도구 호출 항목도 필요하다면 전체 응답을 보관하세요.

Node.js에서 Astra 호출하기

SDK를 설치합니다.

npm install openai

astra-example.mjs 같은 서버 측 파일을 만드세요.

import OpenAI from "openai";

const apiKey = process.env.OMNIAKEY_API_KEY;
if (!apiKey) throw new Error("OMNIAKEY_API_KEY is required");

const client = new OpenAI({
  apiKey,
  baseURL: "https://api.omniakey.com/v1",
});

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "medium" },
  input: "이 API 설계를 검토하고 장애 형태 두 가지와 각각의 테스트 하나를 찾으세요.",
});

console.log(response.output_text);

환경 변수가 설정된 셸에서 실행합니다.

node astra-example.mjs

이 코드는 서버, 로컬 컴퓨터 또는 신뢰할 수 있는 워커에서 실행하세요. 프런트엔드 bundle에 들어간 키는 방문자에게 노출됩니다.

Codex CLI에서 GPT-6 Astra 사용하기

Codex의 사용자 지정 provider는 Responses wire format을 사용합니다. 사용자 설정 파일인 ~/.codex/config.toml에 다음을 추가하세요.

model = "gpt-6-astra"
model_provider = "omniakey"

[model_providers.omniakey]
name = "OmniaKey"
base_url = "https://api.omniakey.com/v1"
env_key = "OMNIAKEY_API_KEY"
wire_api = "responses"

키가 설정된 셸에서 Codex를 시작합니다.

export OMNIAKEY_API_KEY="your-omniakey-api-key"
codex

requires_openai_auth는 설정하지 마세요. Codex 공식 설정 참조는 이 값을 OpenAI 인증 플래그로 정의합니다. 이 사용자 지정 provider는 대신 env_key로 인증합니다.

먼저 Codex에 표시되는 모델을 확인하고, 편집을 허용하기 전에 작은 읽기 전용 작업을 실행하세요. 직접 cURL 요청은 성공하지만 Codex가 실패한다면 클라이언트 설정부터 확인합니다.

필요한 클라이언트에서만 Chat Completions 사용하기

GPT-6 Astra는 Chat Completions에서도 일반 텍스트를 받을 수 있습니다. 클라이언트가 아직 Responses를 지원하지 않을 때 다음 경로를 사용하세요.

curl https://api.omniakey.com/v1/chat/completions \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "reasoning_effort": "medium",
    "messages": [
      {"role": "user", "content": "이 출시 계획의 주요 위험 두 가지를 요약하세요."}
    ]
  }'

매개변수 차이에 주의하세요. Responses는 reasoning.effort, Chat Completions는 reasoning_effort를 사용합니다. 이 Chat Completions 예시에 Astra 도구를 붙이지 마세요. OpenAI의 현재 가이드는 Astra 도구 호출에 Responses를 요구합니다.

reasoning effort 선택하기

Astra는 low, medium, high, xhigh, max를 지원하지만 none은 지원하지 않습니다. 높은 effort는 정답을 보장하지 않으면서 추론 작업, 지연 시간, 출력 토큰 비용을 늘릴 수 있습니다. 인수 테스트를 통과하는 가장 낮은 값을 사용하세요.

Astra에 검증 가능한 작업 주기

좋은 첫 프롬프트에는 목표, 관련 컨텍스트, 제약 조건, 완료 검사를 명시합니다.

목표: 이 데이터베이스 마이그레이션의 배포 위험을 검토한다.
컨텍스트: PostgreSQL 15, 프로덕션 writer는 하나, 롤백은 5분 안에 끝나야 한다.
제약: 파괴적인 명령을 제안하지 말고 검증된 사실과 가정을 구분한다.
완료 조건: 가장 큰 위험 세 가지와 각각의 완화책 하나, 인수 테스트 하나를 반환한다.

코딩 작업에는 저장소 규칙과 완료를 증명하는 정확한 명령도 적으세요. Astra는 접근할 수 있는 지침 파일을 주의 깊게 따르므로 도구 접근 권한을 주기 전에 AGENTS.md, skills, 유사 파일을 검토하세요.

자주 발생하는 설정 오류 해결하기

401, unauthorized 또는 잘못된 API 키

명령을 실행하는 같은 셸에 OMNIAKEY_API_KEY가 설정되어 있는지 확인하세요. 환경 변수에는 키만 넣고 Bearer는 HTTP 헤더에만 붙입니다. 키가 활성 상태이며 만료되지 않았는지도 확인합니다.

잔액 또는 한도 부족

계정 잔액과 키 자체의 한도를 모두 확인하세요. 계정에 잔액이 있어도 범위가 제한된 키가 한도에 도달하면 실패할 수 있습니다.

모델을 찾을 수 없거나 사용할 수 없음

정확한 ID gpt-6-astra를 사용하세요. 현재 모델 페이지를 열고 이 키에 모델 사용 권한이 있는지 확인합니다. GPT 6 같은 표시 이름은 API ID가 아닙니다.

지원하지 않는 매개변수

temperature, top_p, top_logprobs를 제거하세요. Chat Completions에서는 logprobs도 제거하고 Responses의 include에서 message.output_text.logprobs를 빼야 합니다. Astra는 이 매개변수를 지원하지 않습니다.

응답이 incomplete이거나 표시 텍스트가 없음

max_output_tokens를 늘리고 output_tokens_details.reasoning_tokens를 확인하세요. 추론 토큰은 표시 답변이 완성되기 전에 출력 예산을 사용합니다.

채팅은 되지만 도구가 실패함

워크플로를 /v1/responses로 옮기세요. 먼저 일반 텍스트 Responses 호출을 확인하고, 그다음 도구를 하나씩 추가하면서 요청, 결과, 시간 초과, 권한 경로를 검증합니다. OpenAI 공식 도구 목록은 모델에 직접 연결했을 때의 기능을 설명하므로 게이트웨이나 클라이언트가 제공하는 범위는 더 좁을 수 있습니다.

Codex가 계속 다른 모델을 사용함

활성 Codex 설정에서 model, model_provider, base_url, env_key, wire_api를 확인하세요. 그런 다음 OMNIAKEY_API_KEY가 설정된 셸에서 Codex를 다시 시작합니다.

프로덕션 전에 비용 확인하기

대표 작업 하나를 실행하고 사용량 기록을 확인한 뒤 재시도까지 전체 비용에 포함하세요. Astra 모델 페이지가 현재 OmniaKey 가격을 관리합니다. Astra 리뷰는 게이트웨이 가격과 OpenAI 직접 요금을 구분하고 직접 요금이 달라지는 272K 경계를 설명합니다.

사용량 제한으로 작업이 멈췄다면 Codex 사용량 제한 해결 가이드에서 초기화 시간 확인법과 추가 크레딧, 요금제 변경, 별도 과금 로컬 API를 비교하세요.

참고 자료

아래 OpenAI 공식 자료는 모두 영문이며, OmniaKey 문서 링크도 현재 영문 페이지로 이동합니다.

• OpenAI: GPT-6 Astra 모델
• OpenAI: GPT-6 Astra 사용 가이드
• OpenAI: Codex 설정 참조
• OmniaKey API 빠른 시작(영문)
• OmniaKey OpenAI 호환 API(영문)
• OmniaKey Codex CLI 가이드(영문)