GPT-6 Astra API 튜토리얼: Responses API로 첫 번째 앱 만들기

GPT-6 Astra로 구축하는 가장 깔끔한 방법은 Responses API입니다. OpenAI는 기본 Astra 요청에 대해 Chat Completions를 지원하지만, 현재 모델 가이드라인에 따르면 도구 호출에는 Responses가 필요합니다. 따라서 웹 검색, 파일 검색, 사용자 정의 함수, 컴퓨터 사용, 이미지 생성, 구조화된 출력 또는 다중 턴 상태가 필요한 새로운 앱에서는 Responses가 실질적인 기본값이 됩니다.

이 튜토리얼은 작은 "프로덕션 브리프 리뷰어"를 구축합니다. 크리에이티브 브리프를 입력받아 누락된 결정 사항을 식별하고, 다른 인터페이스에서 사용할 수 있는 구조화된 결과를 반환합니다. 동일한 아키텍처는 리서치 어시스턴트, 코딩 도구 및 문서 워크플로우에도 적용됩니다.

예시는 의도적으로 좁은 범위로 설정되어 있습니다. 인증, SDK 릴리스 및 제품 액세스는 변경될 수 있으므로, 배포 전에 공식 Responses API 문서와 구현 세부 사항을 비교하세요.

시작하기 전에 필요한 것

OpenAI API 프로젝트에 결제 기능과 gpt-6-astra에 대한 액세스 권한이 필요합니다. ChatGPT 구독과 API 결제는 별개입니다. Astra 모델 페이지에는 현재 무료 티어 API 지원이 나와 있지 않습니다.

Node.js의 경우, 일반적인 패키지 관리자를 통해 최신 OpenAI SDK를 설치하고 API 키를 서버 측 환경 변수에 저장하세요. 브라우저 코드에 포함하거나 리포지토리에 커밋하지 마십시오.

첫 번째 요청에는 세 개의 필드만 필요합니다:

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "medium" },
  input: "이 간단한 내용을 검토해 주세요: 한 택배 기사가 내일로 작성된 편지를 발견합니다."
});

console.log(response.output_text);

output_text는 응답에서 수집된 텍스트를 위한 편의 속성입니다. 프로덕션 애플리케이션은 모든 호출이 정상적으로 완료되었다고 가정하기보다 응답 상태, 오류 및 사용량도 검사해야 합니다.

요청 형태 이해하기

`model`

정확한 모델 식별자 gpt-6-astra를 사용하세요. 공식 카탈로그에 나열되지 않은 별칭이나 날짜가 있는 스냅샷을 추측하지 마세요.

`input`

입력은 문자열 또는 구조화된 콘텐츠일 수 있습니다. Astra는 텍스트와 이미지 입력을 허용합니다. 기본적으로 텍스트를 생성하며, 현재 모델 페이지에서는 오디오와 비디오가 지원되는 모달리티가 아닙니다.

`reasoning`

reasoning.effort 필드는 모델이 적용하는 추론의 양을 제어합니다. Astra는 low, medium, high, xhigh 및 max를 지원합니다. none은 지원하지 않습니다. OpenAI에 따르면 해당 설정은 HTTP 400을 반환합니다.

평가를 위해 중간 설정으로 시작하세요. 더 많은 추론이 항상 경제적이라고 가정하지 말고, 동일한 작업에서 낮은 설정과 높은 설정을 비교하세요.

결과물을 하위 단계에서 활용하세요: 앱에서 승인된 스크립트나 쇼트 브리프가 생성되면, 제작자는 이를 Elser AI로 전송하여 캐릭터 디자인, 스토리보드, 장면 생성 및 편집을 진행할 수 있습니다. 이는 워크플로우 인계일 뿐, 기본 통합을 의미하지는 않습니다.

모델에 실제 출력 계약 제공

일반 단락은 검증하기 어렵습니다. 검토자는 요약, 누락된 결정 사항, 그리고 브리프가 스토리보드 준비가 되었는지 여부를 포함하는 안정적인 객체를 반환해야 합니다.

Structured Outputs를 사용할 때, text.format 아래에 JSON 스키마를 정의하세요:

const briefSchema = {
  type: "object",
  속성: {
    로그라인: { type: "string" },
    missing_decisions: {

번역:   
missing_decisions: {
      type: "array",
      items: { type: "string" }
    },
    ready_for_storyboard: { type: "boolean" }
  },
  필수: ["로그라인", "missing_decisions", "ready_for_storyboard"],
  additionalProperties: false
};

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "medium" },
  지침: [
    "제작 준비 상태를 위해 크리에이티브 브리프를 검토하세요.",
    "누락된 예산, 권리, 관객 또는 런타임 결정을 임의로 만들지 마십시오."
  ].join(" "),
  input: "한 택배기사가 내일로 보내지는 편지를 발견합니다.",
  text: {
    format: {
      type: "json_schema",
      name: "간단 리뷰",
      strict: true,
      스키마: 간략스키마
    }
  }
});

const review = JSON.parse(response.output_text);

스키마 유효성이 사실적 또는 창의적 품질을 보장하지 않습니다. 필요한 비즈니스 규칙도 검증하세요. 예를 들어, ready_for_storyboard는 런타임, 관객 또는 권리 제약 조건이 없을 때 false여야 합니다.

사용자 정의 함수 추가

승인된 캐릭터 기록이 데이터베이스에 있다고 가정해 보세요. 모든 프롬프트에 전체 카탈로그를 붙여넣는 대신 Astra가 기록을 요청하도록 하세요.

개념적으로, 이름, 설명, 엄격한 매개변수 스키마 및 실행 로직을 가진 함수 도구를 정의하세요. 응답에 함수 호출이 포함된 경우:

인수를 분석하고 유효성을 검사합니다;
현재 사용자에 대한 액세스 권한을 부여합니다;
애플리케이션에서 함수를 실행하세요;
원래 call_id를 사용하여 function_call_output을 반환합니다.
Responses 대화를 계속합니다.

모델이 데이터베이스 함수를 실행하지 않습니다. 여러분의 코드가 실행합니다. 도구 설명은 선택을 안내할 뿐이며, 보안 경계가 아닙니다.

GPT-6 Astra는 비동기 도구 호출도 지원합니다. 적격한 함수나 사용자 정의 도구에 async: true를 설정하면 애플리케이션이 도구를 실행하는 동안 모델이 독립적으로 작업을 계속할 수 있습니다. 작업이 완료되면 원래 호출 ID와 함께 이후 Responses 요청에서 출력을 보냅니다. 이는 백그라운드 모드와 다릅니다. 비동기 도구 호출은 모델이 도구 결과를 기다릴지 여부를 변경하는 반면, 백그라운드 모드는 응답 생성 자체와 관련됩니다.

다중 턴 상태 유지

짧은 후속 질문을 위해 이전 응답 ID를 전달하세요:

const first = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "medium" },
  input: "이 6샷 프로덕션 브리프를 검토하세요: ..."
});

const revised = await client.responses.create({
  model: "gpt-6-astra",
  previous_response_id: first.id,
  reasoning: { effort: "medium" },
  input: "30초 세로형 동영상의 리뷰를 수정하세요."
});

OpenAI는 상태를 유지하는 한 가지 방법으로 store: true와 이전 응답을 문서화합니다. 다른 보존 요구 사항이 있는 조직은 지속성 패턴을 맹목적으로 복사하기보다 사용 가능한 상태 비저장 및 암호화된 추론 옵션을 검토해야 합니다.

무제한으로 통제되지 않은 대화 기록을 계속 보내지 마세요. 긴 컨텍스트는 비용을 증가시키고, 오래된 지침을 포함할 수 있으며, 272,000 입력 토큰 이상의 더 높은 가격 임계값을 초과할 수 있습니다.

대화 중 추론 노력 변경

Astra는 표준 단일 에이전트 모드에서 configuration_update 항목을 지원합니다. 이는 캐싱을 위한 요청 수준 프롬프트 접두사를 유지하면서 추론 노력을 높이거나 낮출 수 있습니다.

예를 들어, 일상 점검을 낮은 노력으로 시작한 후 실패 분석으로 확대하십시오:

const next = await client.responses.create({
  model: "gpt-6-astra",
  previous_response_id: first.id,
  reasoning: { effort: "low" },
  input: [
    { type: "configuration_update", reasoning: { effort: "high" } },
    {
      role: "사용자",
      content: "연속성 오류를 찾아 최소한의 수정을 제안합니다."
    }
  ]
});

공식 추론 가이드는 호환성 제한 사항을 명시합니다: 구성 업데이트는 Astra 전용이며, 표준 단일 에이전트 모드에서 적용되며, 기록에서 인접할 수 없고 자동 압축 또는 잘림과 결합되지 않습니다. 광범위하게 채택하기 전에 현재 가이드를 읽으십시오.

이미지를 신중하게 추가하세요

이미지 입력을 통해 리뷰어가 스토리보드 프레임과 캐릭터 개요를 비교하는 데 도움을 줄 수 있습니다. 구조화된 입력에 텍스트와 input_image 항목을 제공하세요. 모델에게 가시적인 관찰과 추론을 분리하도록 요청하세요.

예를 들어, 헤어스타일, 액세서리 방향, 팔레트 및 의상 구성을 포함한 체크리스트를 요청하세요. 외모에서 성격을 추론하거나 이미지가 불명확할 때 작은 시각적 세부 사항을 확실한 것으로 간주하도록 요청하지 마십시오.

결과가 프로덕션 용도라면, Elser AI에 저장하기 전에 사람이 신원 규칙을 승인하도록 하세요. 시각적 분석은 검토 작업을 줄일 수 있지만, 대체할 수는 없습니다.

오류 및 불완전한 응답 처리

프로덕션 코드는 네트워크 장애 이상의 상황을 처리해야 합니다. 다음을 확인하세요:

인증 및 프로젝트 접근 오류;
지원되지 않는 필드나 추론 값으로 인한 HTTP 400;
속도 제한;
출력 제한으로 인한 불완전한 응답;
도구 호출 인수 검증 실패;
만료된 외부 작업;
스키마는 유효하지만 의미상 사용할 수 없는 출력;
사용자 취소 및 시간 제한.

일시적인 오류에 대해서는 백오프를 적용한 제한된 재시도를 사용하세요. 유효하지 않은 요청은 변경 없이 재시도하지 마세요. 민감한 콘텐츠를 불필요하게 저장하지 않고 요청 식별자, 모델, 지연 시간, 토큰 사용량 및 도구 결과를 기록하세요.

Astra와 함께 피해야 할 매개변수

OpenAI의 현재 Astra 마이그레이션 가이드라인은 temperature, top_p 및 top_logprobs를 제거하라고 명시합니다. Chat Completions 요청은 logprobs도 제거해야 하며, Responses 요청은 include에서 message.output_text.logprobs를 생략해야 합니다.

일반 API 참조에서 복사된 예시는 다른 모델에서 허용되는 필드를 보여줄 수 있습니다. 모델별 지침이 Astra 요청을 관리합니다.

애플리케이션을 테스트하세요, 모델만이 아니라

작은 평가 세트를 만드세요. 다음이 포함되어야 합니다:

완료된 브리프;
런타임 또는 시청자가 누락된 브리핑;
충돌하는 캐릭터 세부 정보;
업로드된 문서 내의 악성 명령어;
세부 사항이 모호한 이미지;
거부되어야 하는 함수 호출;
비용 한계에 매우 가까운 아주 긴 브리핑.

최초 수용률, 구조화된 출력 유효성, 지원되지 않는 주장, 도구 성공률, 지연 시간, 토큰 비용, 인간 교정 시간을 측정하십시오. 권한 및 외부 데이터가 기본 텍스트 프롬프트로 해결할 수 없는 위험을 만들기 때문에 전체 도구 루프를 레드 팀으로 검토하십시오.

API 출력에서 애니메이션으로

샘플 리뷰어는 추론과 렌더링 사이에 명확한 경계를 만듭니다. 검증된 로그라인, 누락된 결정 사항 및 스토리보드 준비 상태를 반환할 수 있습니다. 프로덕션 서비스는 캐릭터 잠금, 시간별 샷 및 연속성 규칙으로 스키마를 확장할 수 있습니다.

승인 후 Elser AI를 사용하여 캐릭터와 스토리보드를 구축하고, 장면 자산을 생성하며, 음성이나 음악을 추가하고 최종 컷을 조립하세요. API 결과를 버전 관리하여 프로덕션 변경 사항을 추적 가능하게 유지하세요.

자주 묻는 질문

GPT-6 Astra에 어떤 API를 사용해야 하나요?

새 프로젝트와 도구 호출에는 Responses API를 사용하세요. 기본적인 채팅 완성 요청은 지원되지만, Astra 도구 호출에는 Responses가 필요합니다.

GPT-6 Astra 모델 ID란 무엇인가요?

gpt-6-astra를 사용하세요.

GPT-6 Astra의 온도를 설정할 수 있나요?

OpenAI의 현재 마이그레이션 가이드라인은 temperature, top_p 및 top_logprobs를 제거하라고 명시하고 있습니다.

GPT-6 Astra는 JSON 출력을 지원하나요?

네. 구조화된 출력이 지원됩니다. 비공식적인 형식 지정 지침을 신뢰하기보다는 적절한 JSON 스키마를 정의하고 검증하세요.

GPT-6 Astra가 내 애플리케이션 함수를 호출할 수 있나요?

네. 모델이 함수 호출을 요청할 수 있지만, 애플리케이션이 권한을 확인하고 코드를 실행한 후 결과를 반환합니다.

GPT-6 Astra가 API 무료 등급에서 사용 가능한가요?

현재 모델 페이지에서는 Free 등급이 지원되지 않는 것으로 표시되어 있습니다.

결론

신뢰할 수 있는 GPT-6 Astra 앱은 Responses API, 명시적 추론 설정, 그리고 소프트웨어가 검증할 수 있는 출력 계약에서 시작됩니다. 승인과 관찰 가능성(observability)이 있는 경우에만 도구를 추가하고, 대화 상태를 제한된 범위로 유지하며, 이상적인 입력만큼이나 실패 사례도 신중하게 테스트하세요.

크리에이티브 시스템의 경우 Astra를 사용하여 브리프를 정확하고 검토 가능하게 만드세요. 그런 다음 승인된 스크립트와 샷 데이터를 Elser AI로 전송하여 시각적 제작을 진행하세요.