# 모델 가이드 | 오픈AI API ## 소개 GPT-5.6은 복잡한 프로덕션 워크플로를 위한 품질과 효율성의 새로운 기준을 제시합니다. GPT-5.6은 특히 토큰 효율이 높으며, 레이아웃, 시각적 계층, 디자인 판단 등 프런트엔드 미적 품질을 개선합니다. GPT-5.6은 새로운 명명 체계도 도입합니다. `gpt-5.6` 별칭은 플래그십 성능을 제공하는 모델인 `gpt-5.6-sol`로 요청을 라우팅합니다. 더 낮은 가격으로 강력한 성능이 필요하면 `gpt-5.6-terra`를 사용하고, 효율적인 대량 워크로드에는 `gpt-5.6-luna`를 사용하세요. GPT-5.5 또는 GPT-5.4에서 마이그레이션할 때는 현재 GPT-5.5 또는 GPT-5.4의 추론 설정으로 시작하세요. 그런 다음 대표 작업에서 동일한 설정과 한 단계 낮은 설정을 테스트합니다. GPT-5.6은 더 적은 토큰으로 품질을 유지하거나 높일 때가 많지만, 최적의 설정은 워크로드에 따라 달라집니다. ## 새로운 기능 - **프로그래밍 방식 도구 호출(Programmatic Tool Calling):** GPT-5.6은 자바스크립트를 작성해 적격 도구를 호출하고, 호출 간 결과를 전달하며, 호스팅 런타임에서 중간 출력을 처리할 수 있습니다. 각 단계 사이에 새로운 모델 판단이 필요하지 않은, 범위가 정해진 도구 중심 워크플로에는 [프로그래밍 방식 도구 호출](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling)을 사용하세요. 프로그래밍 방식 도구 호출은 추가 컨테이너 비용 없이 ZDR과 호환됩니다. - **다중 에이전트 \[베타\](Multi-agent \[beta\]):** [다중 에이전트](https://developers.openai.com/api/docs/guides/responses-multi-agent)를 사용하면 GPT-5.6 인스턴스가 여러 하위 에이전트를 병렬로 조율하고 그 결과를 종합할 수 있습니다. 코덱스의 울트라 모드와 비슷하게, 독립적인 작업 흐름으로 깔끔하게 나눌 수 있는 복잡한 작업에서 실제 소요 시간을 줄이고 성능을 높일 수 있습니다. 다중 에이전트는 개발자 피드백을 반영해 개선하는 동안 Responses API의 베타 기능으로 제공됩니다. - **명시적 프롬프트 캐싱(Explicit prompt caching):** GPT-5.6에서는 재사용 가능한 프롬프트 접두사 중 오픈AI가 정확히 무엇을 캐시할지 표시할 수 있습니다. 암시적 모드에서 자동 캐싱도 계속 사용할 수 있습니다. 오픈AI는 캐시 쓰기에 캐시되지 않은 입력 요율의 1.25배를 청구하며, 캐시 읽기에는 계속 할인 요율이 적용됩니다. [프롬프트 캐싱을 구성하는 방법](https://developers.openai.com/api/docs/guides/prompt-caching)을 알아보세요. - **지속 추론(Persisted reasoning):** GPT-5.6은 여러 턴의 품질과 캐시 효율을 높이기 위해 사용 가능한 추론 항목을 턴 간에 재사용할 수 있습니다. `reasoning.context`로 동작을 선택하세요. [호출 간 추론을 보존하는 방법](https://developers.openai.com/api/docs/guides/reasoning#preserve-reasoning-across-calls)을 알아보세요. - **최대 추론 노력(Max reasoning effort):** GPT-5.6은 더 많은 탐색과 검증이 필요한 까다로운 작업을 위해 `max` 추론 노력을 지원합니다. 현재 `xhigh`를 사용하고 있다면 대표 워크로드에서 두 설정을 비교하세요. - **프로 모드(Pro mode):** GPT-5.6은 어려운 작업에서 신뢰성을 높이기 위해 더 많은 모델 작업을 수행하고 하나의 최종 답변을 반환할 수 있습니다. 지연 시간과 토큰 사용량보다 품질이 더 중요할 때 `reasoning.mode: "pro"`로 활성화하세요. [프로 모드를 사용하는 방법](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode)을 알아보세요. - **토큰 효율(Token efficiency):** GPT-5.6은 더 적은 출력 토큰으로 최전선 성능에 도달합니다. - **프런트엔드 디자인(Frontend design):** GPT-5.6은 레이아웃, 시각적 계층, 디자인 판단이 더 뛰어나며, 더 정제되고 사용하기 쉬운 웹사이트와 애플리케이션을 만듭니다. - **의도 이해(Intent understanding):** GPT-5.6은 문맥에서 사용자의 근본 목표와 의도한 작업 수준을 더 잘 추론할 수 있습니다. 따라서 모든 단계를 일일이 지시하지 않아도 되는 경우가 많습니다. 그래도 도메인 맥락, 엄격한 제약, 승인 경계, 성공 기준은 계속 제공하세요. 중요한 모호성이 있으면 질문해야 한다고 모델에 알려야 합니다. - **원본 이미지 세부 정보(Original image detail):** GPT-5.6은 `original` 또는 `auto` 세부 수준으로 전송된 이미지의 원본 크기를 유지합니다. 패치 예산이나 픽셀 크기 제한에 맞춰 크기를 조정하지 않습니다. 큰 이미지는 입력 토큰을 더 많이 사용하고 지연 시간을 늘릴 수 있습니다. [이미지 세부 수준을 선택하는 방법](https://developers.openai.com/api/docs/guides/images-vision#choose-an-image-detail-level)을 알아보세요. ## 안전장치 GPT-5.6 모델을 사용할 때, 사용자는 일부 요청이 차단되거나 거부되는 안전장치를 접할 수 있습니다. 이는 모델 출력이 생성되는 동안 실시간 사이버 및 생물학 오용 분류기가 실행되기 때문입니다. 다른 요청은 생성 도중 스트림이 몇 초 동안 일시 중지되고, 이 분류기들이 출력을 동기적으로 검토하느라 더 오래 걸릴 수 있습니다. 안전장치는 때때로 정당한 작업에도 개입할 수 있습니다. 특히 방어적 활동과 공격적 활동이 처음에는 비슷해 보일 수 있는 이중용도 영역에서 그렇습니다. 애플리케이션이 개별 최종 사용자에게 서비스를 제공한다면 각 요청에 안정적이고 개인정보를 보호하는 `safety_identifier`를 보내세요. 지침은 [안전 식별자 구현](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers)을 참고하세요. 저희는 이러한 안전장치를 지속적으로 발전시키고 있습니다. 적대적 압력에도 견고하고 효과적으로 대응하는 동시에 코드 리뷰, 취약점 연구, 패치 개발, 디버깅, 보안 교육, 방어적 테스트 같은 정당한 작업에 대한 접근은 보존하기 위해서입니다. ## 마이그레이션 빠른 시작 ### 코덱스로 마이그레이션하기 코덱스는 [오픈AI 문서 스킬](https://github.com/openai/skills/tree/main/skills/.curated/openai-docs)을 사용해 이 가이드의 권장 변경 사항을 적용할 수 있습니다. ```text $openai-docs migrate this project to the GPT-5.6 model family ``` 다른 코딩 에이전트에서 이 스킬을 사용하려면 [오픈AI 스킬 저장소](https://github.com/openai/skills/tree/main/skills/.curated/openai-docs)에서 다운로드하세요. ### API 및 모델 매개변수 업데이트하기 - 워크로드에 맞는 대상 모델을 선택하세요. 최전선 성능에는 `gpt-5.6-sol`, 지능과 비용의 균형에는 `gpt-5.6-terra`, 효율적인 대량 워크로드에는 `gpt-5.6-luna`를 사용합니다. `gpt-5.6` 별칭은 요청을 `gpt-5.6-sol`로 라우팅합니다. - 추론, 도구 호출, 여러 턴 워크플로에는 [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses)를 사용하세요. - `reasoning.effort`를 의도적으로 설정하세요. GPT-5.6은 `none`, `low`, `medium`, `high`, `xhigh`, `max`를 지원합니다. - GPT-5.5 또는 GPT-5.4에서 마이그레이션한다면 현재 추론 노력을 기준선으로 유지한 뒤 한 단계 낮은 설정과 비교하세요. - `none`을 사용한다면 지연 시간 기준선으로 그대로 유지하고, 워크플로가 추론이나 도구 사용의 이점을 얻을 때는 `low`도 테스트하세요. - 균형 잡힌 시작점으로는 `medium`을 사용하고, 지연 시간에 민감한 워크로드에는 `low`를 사용하세요. - 더 많은 추론이 측정 가능한 품질 향상을 가져올 때는 `high` 또는 `xhigh`를 사용하세요. - `max`는 품질이 최우선인 가장 어려운 워크로드에만 남겨 두세요. 사용 사례에 가장 적합한 품질, 지연 시간, 비용의 절충점을 찾기 위해 `max`와 `xhigh`를 비교합니다. - 프로 모드를 사용하려면 선택한 GPT-5.6 모델을 유지하고 Responses API에서 `reasoning.mode`를 `pro`로 설정하세요. 별도의 Pro 모델 슬러그로 전환하지 마세요. `reasoning.effort`는 독립적으로 선택합니다. 생략하면 GPT-5.6은 표준 모드와 프로 모드 모두에서 기본값으로 `medium`을 사용합니다. 요청 예시와 과금 세부 정보는 [추론 모드](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode)를 참고하세요. - 이전 추론이 얼마나 계속 관련이 있는지에 따라 지속 추론을 구성하세요. - 모델의 기본값을 사용하려면 `reasoning.context`를 생략하거나 `auto`로 설정하세요. 실제 적용된 모드를 확인하려면 응답의 `reasoning.context` 필드를 확인합니다. - 작업의 목표, 가정, 우선순위가 턴 간에 안정적으로 유지될 때는 `reasoning.context`를 `all_turns`로 설정하세요. - `all_turns`에서는 이전 응답의 추론을 모델이 사용할 수 있도록 `previous_response_id`로 이어 가세요. - 기록을 수동으로 관리할 때는 이전 사용자 입력과 모든 응답 출력 항목을 보존하고 다시 보내세요. `store: false` 또는 제로 데이터 보존(Zero Data Retention)의 경우 `include: ["reasoning.encrypted_content"]`를 추가하고 반환된 암호화 추론 항목을 재생합니다. - 이전 추론이 더 이상 관련이 없을 때는 `reasoning.context`를 `current_turn`으로 설정하세요. - 프롬프트 캐싱을 검토하세요. 암시적 캐싱을 계속 사용하기 위해 코드를 변경할 필요는 없습니다. GPT-5.6 캐시 쓰기는 캐시되지 않은 입력 요율의 1.25배가 들기 때문에 `cached_tokens`와 `cache_write_tokens`를 추적해 순비용을 파악하세요. 불필요한 쓰기를 피하려면 명시적 중단점이나 `prompt_cache_options.mode: "explicit"`을 사용하고, `prompt_cache_retention`은 `prompt_cache_options.ttl`로 교체하세요. - 프로그래밍 방식 도구 호출을 사용하려면 `programmatic_tool_calling` 도구를 추가하고 `allowed_callers`로 적격 도구를 옵트인하세요. 애플리케이션이 `program` 항목, 프로그램이 발행한 함수 호출, `program_output` 항목을 처리하도록 업데이트하되 각 호출의 `call_id`와 `caller` 연결은 보존해야 합니다. 요청 및 계속 진행 예시는 [프로그래밍 방식 도구 호출 가이드](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling)를 참고하세요. - PTC가 활성화된 워크플로를 대표 작업에서 벤치마크하세요. 작업 성공률, 최종 답변의 완전성, 필요한 증거, 총 토큰, 지연 시간, 비용을 비교합니다. 호출, 턴 또는 중간 출력이 줄어드는 것은 최종 답변이 여전히 필요한 품질 기준을 충족할 때만 개선으로 봐야 합니다. ## 프롬프트 작성 모범 사례 ### 더 간결한 프롬프트를 선호하기 반복되는 지침과 예시를 제거하고 도구 설명을 단순화하면 작업 성능과 토큰 효율을 높일 수 있습니다. 내부 코딩 에이전트 평가 실행 샘플에서는 더 간결한 시스템 프롬프트를 사용한 구성이 평가 점수를 약 10~15% 높였습니다. 동시에 총 토큰은 41~66%, 비용은 33~67% 줄었습니다. 결과는 워크로드에 따라 달라질 수 있으므로 이 범위는 방향성으로만 보고, 자체 애플리케이션의 대표 작업에서 변경 사항을 검증하세요. 중요한 지침을 잃지 않으면서 프롬프트를 단순화하려면 다음을 따르세요. - 이미 잘 작동하는 프롬프트와 도구 집합에서 시작하세요. 지침, 예시 또는 도구 그룹을 한 번에 하나씩 제거한 뒤 같은 평가를 다시 실행합니다. - 각 지침은 한 번만 명시하세요. - 작업과 관련된 도구만 노출하고, 설명은 간결하고 정확하게 유지하세요. - 제품 요구사항을 담고 있거나 측정된 격차를 바로잡는 예시와 스타일 지침은 유지하세요. - 실행 시작 시점과 대화가 길어지는 과정 모두에서 컨텍스트를 추적하세요. 긴 세션에서는 반복되는 프롬프트와 도구 콘텐츠의 영향이 커질 수 있습니다. ### 자율성과 승인 경계 정의하기 GPT-5.6은 여러 단계 작업을 수행할 때 능동적이고 끈기 있게 진행할 수 있습니다. 각 요청이 어떤 수준의 행동을 승인하는지 정의하세요. 그러면 모델은 불필요하게 멈추지 않고 안전하며 범위 안에 있는 작업을 계속할 수 있고, 외부 작업, 파괴적 작업, 비용이 드는 작업, 범위를 확장하는 작업 앞에서는 멈출 수 있습니다. 간결한 정책이면 대체로 충분합니다. ```text 답변, 설명, 검토, 진단 또는 계획을 요청받으면 관련 자료를 검토하고 결과를 보고합니다. 요청에서 변경 구현도 요구하지 않는 한 변경을 구현하지 마세요. 변경, 구축 또는 수정을 요청받으면 요청받은 범위 안의 로컬 변경을 수행하고 먼저 묻지 않고 관련된 비파괴 검증을 실행하세요. 외부 쓰기, 파괴적 작업, 구매 또는 범위의 중대한 확장에는 확인을 요구하세요. ``` 파일 읽기, 로그 검사, 범위 안의 코드 편집, 테스트 실행처럼 안전한 로컬 작업은 명시적으로 이름을 붙이세요. 정책은 한곳에 두고 각 규칙은 한 번만 적습니다. “먼저 물어보라”, “변경하지 말라”, “승인을 기다리라” 같은 지침을 반복하면 안전하고 예상 가능한 작업에도 불필요한 승인 요청이 발생할 수 있습니다. ### 응답 길이와 스타일 설정하기 GPT-5.6은 기본적으로 GPT-5.5보다 더 간결한 경향이 있습니다. 마이그레이션할 때는 “간결하게 답하라” 또는 “짧게 유지하라”처럼 폭넓은 간결성 지침이 여전히 유용한지 확인하세요. 일부 작업에는 불필요할 수 있고, 때로는 응답을 지나치게 짧게 만들 수 있습니다. 애플리케이션에 필요한 출력을 안정적으로 만들어 낼 때만 유지하세요. 요청 전반에서 더 일관되게 제어하려면 `text.verbosity`로 기본 세부 수준을 설정한 뒤, 작업별 요구사항은 프롬프트에서 지정하세요. #### text.verbosity로 기본값 설정하기 요청의 기본 세부 수준으로 `low`, `medium`, `high` 중 하나를 선택하세요. 프롬프트에는 작업별 길이, 구조 또는 필수 콘텐츠를 지정합니다. API 예시는 [`text.verbosity` 설정](https://developers.openai.com/api/docs/guides/deployment-checklist#set-up-textverbosity)을 참고하세요. #### 짧은 답변에 반드시 포함할 내용 지정하기 작업에 더 짧은 답변이 필요할 때는 모델이 보존해야 할 정보와 생략해도 되는 세부 정보를 식별하세요. 예를 들면 다음과 같습니다. ```text 결론으로 시작하세요. 결론을 뒷받침하는 데 필요한 증거, 중요한 주의사항, 다음 조치를 포함하세요. 부차적인 세부 정보와 반복은 생략하세요. 필수 사실, 결정, 주의사항, 다음 단계는 모두 유지하세요. 도입부, 반복, 일반적인 안심 표현, 선택적 배경 설명을 먼저 줄이세요. ``` 이렇게 하면 모델에 명확한 우선순위가 생깁니다. 작업을 완료하는 데 필요한 콘텐츠를 보존한 뒤, 가치가 낮은 세부 정보를 제거합니다. #### 어조 정의하기 “친근한” 또는 “공감하는” 같은 넓은 라벨은 모호할 수 있습니다. 제품의 어조를 정의하는 글쓰기 선택을 설명하세요. 예를 들어 답변을 얼마나 직접적으로 말할지, 문제를 언제 인정할지, 안심시키는 표현이나 맺음말이 적절한지를 설명합니다. ```text 답변을 직접적으로 제시하세요. 사용자가 문제를 보고하면 다음 단계를 안내하기 전에 구체적인 문제를 인정하세요. 안심시키는 표현은 관련이 있을 때만 사용하세요. 일반적인 칭찬과 불필요한 맺음말은 생략하세요. ``` ### 프로 모드 #### 품질이 가장 중요할 때 프로 모드 선택하기 프로 모드는 Responses API 실행 모드입니다. 단일 최종 답변을 반환하기 전에 요청에 더 많은 모델 작업을 적용합니다. 어려운 작업에서 신뢰성을 높일 수 있지만 지연 시간이 늘어나고, 보고된 사용량에 해당 작업의 토큰이 합산됩니다. 이 토큰에는 선택한 모델의 표준 토큰 요율이 적용됩니다. 한계적인 품질 향상이 결과에 실질적인 영향을 주고, 작업이 그 이점을 얻을 만큼 어려울 때 프로 모드를 사용하세요. 예로는 복잡한 최적화, 높은 가치의 코딩 또는 리뷰, 명확한 평가 기준이 있는 심층 분석이 있습니다. 일반적인 작업, 지연 시간에 민감한 작업, 대량 작업에는 표준 모드를 선호하세요. 평가에서 프로 모드의 의미 있는 이점이 나타나지 않을 때도 표준 모드를 사용합니다. 추론 모드와 추론 노력은 독립적입니다. 프로 모드는 모든 GPT-5.6 모델 및 해당 모델이 지원하는 추론 노력과 함께 작동합니다. 표준 모드 기준선과 같은 모델 및 노력으로 시작한 뒤 대표 작업에서 구성을 비교하세요. 가장 높은 노력이 항상 최적의 절충점이라고 가정하지 마세요. #### API에서 프로 모드 구성하기 API 요청에서 프로 모드를 활성화하세요. 표준 모드에서 사용하는 것과 같은 결과 중심 프롬프트를 유지합니다. 목표, 관련 맥락, 제약, 필요한 증거, 성공 기준, 출력 형식을 명시하세요. 모델에 “프로 모드를 사용하라”, “더 깊이 생각하라”, “여러 후보 답변을 생성하라”고 요청할 필요는 없습니다. 예를 들면 다음과 같습니다. ```text 이 데이터베이스 마이그레이션 계획에서 데이터 손실이나 장시간 중단을 일으킬 수 있는 실패 모드를 검토하세요. 각 발견 사항에 대해 관련 단계를 인용하고, 영향과 가능성을 추정하며, 구체적인 완화책을 권장하세요. 가장 중요한 위험 다섯 가지를 심각도 순서로 반환하세요. ``` #### 품질과 비용 비교하기 같은 대표 작업에서 표준 모드와 프로 모드를 비교하세요. 작업 성공률, 답변의 완전성, 필요한 증거, 총 토큰, 지연 시간, 비용을 측정합니다. 프로 모드는 품질이나 신뢰성 향상이 추가 모델 작업을 정당화하는 경우에만 선택적으로 사용하세요. 자세한 내용은 [추론 모드 가이드](https://developers.openai.com/api/docs/guides/reasoning#reasoning-mode)를 참고하세요. ### 프로그래밍 방식 도구 호출 #### 작업 형태에 따라 프로그래밍 방식 도구 호출 선택하기 프로그래밍 방식 도구 호출(PTC)은 코드가 여러 도구 결과나 큰 중간 출력을 처리해 훨씬 더 작은 구조화 결과를 반환할 수 있는, 범위가 정해진 워크플로에 가장 적합합니다. 필터링, 조인, 순위 지정, 중복 제거, 집계, 검증 또는 기타 예측 가능한 처리에 사용하세요. 호출이 여러 개이거나 병렬이거나 서로 의존한다는 사실만으로는 프로그래밍 방식 도구 호출을 정당화할 수 없습니다. 다음 경우에는 직접적인 비 PTC 도구 호출을 선호하세요. - 한 번의 호출로 충분한 경우 - 중간 출력이 이미 작은 경우 - 각 결과가 모델의 다음 결정을 바꿀 수 있는 경우 - 어떤 작업에 승인이 필요한 경우 - 최종 출력이 인용이나 네이티브 산출물을 보존해야 하는 경우 #### 라우팅 지침을 작업별로 만들기 올바른 경로가 선택되도록 도구의 사용 가능 여부나 “프로그래밍 방식 도구 호출을 효율적으로 사용하라” 같은 일반 지침에 의존하지 마세요. 직접 호출과 프로그래밍 방식 호출을 모두 사용할 수 있을 때는 다음을 명시하세요. - 프로그래밍 방식 도구 호출을 사용해야 하는 범위가 정해진 단계 - 호출할 수 있는 도구 - 정확한 출력 스키마와 필요한 증거 - 동시성, 재시도, 중단 제한 - 직접 호출로 남겨 두어야 하는 작업 도구 설명에는 예상 반환 필드, 유형, 오류 동작을 문서화해야 합니다. 모델이 프로그램을 작성하기 전에 반환 형태를 파악할 수 없다면 직접 도구 호출을 선호하세요. 그래야 결과를 검사한 뒤 사용 방법을 결정할 수 있습니다. 두 경로가 모두 필요하다면 명확한 인계 지점을 하나 정의하고, 모델에 경로를 전환하거나 완료된 작업을 반복하지 말라고 알려 주세요. 예를 들면 다음과 같습니다. ```text <tool_orchestration> [범위가 정해진 단계]에는 [적격 도구]만 사용해 프로그래밍 방식 도구 호출을 사용하세요. 안전할 때는 독립적인 호출을 동시에 실행하세요. 문서화된 도구 입력 및 출력 필드만 사용하세요. 중간 결과를 처리하고 축소한 뒤, 최종 답변에 필요한 증거를 포함해 정확히 [출력 스키마]를 내보내세요. [조건]이 충족되면 중단하세요. 일시적 실패는 최대 [R]번 재시도하세요. 완료된 호출을 반복하거나 부작용이 있는 작업을 수행하지 마세요. 필요한 결과가 여전히 누락되어 있다면 명확한 구조화 실패를 반환하세요. [의미 판단, 승인 또는 최종 검증]에는 직접 도구 호출을 사용하세요. </tool_orchestration> ``` #### 최종 답변 평가하기 `program_output` 항목과 최종 어시스턴트 `message`는 별도의 출력입니다. 둘 다 테스트해야 합니다. 이론적으로는 프로그램이 올바른 레코드를 반환했지만 메시지에서 필수 필드, 인용 또는 주의사항을 빠뜨릴 수 있습니다. 같은 대표 작업에서 직접 호출과 프로그래밍 방식 호출을 비교하세요. 최종 응답이 정확하고 완전하며 필요한 증거를 포함하는지 확인합니다. 그런 다음 총 토큰, 지연 시간, 비용, 호출, 턴, 재시도를 비교하세요. 리소스 사용량 감소는 응답이 기존 평가를 계속 통과할 때만 개선으로 계산합니다. 자세한 내용은 [프로그래밍 방식 도구 호출 가이드](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling)를 참고하세요.