Unity에서 OpenAI API 시작하기

Unity에서 OpenAI API 시작하기

API 키 발급부터 첫 텍스트 생성 테스트까지 정리

이번 작업에서는 Unity 프로젝트 안에서 OpenAI API를 직접 호출할 수 있는 환경을 먼저 만들고, 가장 기본적인 기능인 텍스트 생성까지 확인해봤다. 목표는 단순했다. Unity 안에서 OpenAI SDK가 정상적으로 연결되는지 확인하고, 키 입력 한 번으로 모델 응답이 Console에 출력되는 최소 테스트를 통과시키는 것이었다. 문서 기록 기준으로는 OpenAI 플랫폼에서 API 키를 발급하고, Unity Package Manager에 OpenUPM 레지스트리를 추가한 뒤, OpenAI 패키지를 설치하고 OpenAIConfiguration에 API 키를 연결하는 흐름으로 정리되어 있다.

 

이번 글은 이미지 생성이나 음성 기능까지 다루지 않는다. 그 부분은 뒤 글에서 따로 다룰 예정이다. 이번 1편은 어디까지나 기본 세팅 + 텍스트 생성 첫 테스트에 집중한다. 개인적으로도 이런 흐름이 맞다고 봤다. 이미지나 오디오 기능부터 들어가면 인증, 응답 포맷, 파일 처리까지 한꺼번에 복잡해지는데, 텍스트 생성은 구조가 단순해서 Unity에서 OpenAI API 연결이 정상인지 확인하기에 가장 적합했다.

---

1. 먼저 OpenAI API 키부터 준비

가장 먼저 한 일은 OpenAI 플랫폼에서 API를 사용할 프로젝트를 만들고 secret key를 발급받는 것이었다. 문서 기준으로는 플랫폼에 가입한 뒤 프로젝트를 생성하고, 대시보드에서 Create new secret key 버튼을 눌러 API 키를 만들도록 정리되어 있다. 키 이름은 자유롭게 작성할 수 있고, 생성한 프로젝트를 지정한 뒤 권한 범위를 선택해서 발급하면 된다. 그리고 이 키는 생성 직후에 복사해서 따로 보관해야 한다. 기록에도 적혀 있듯, 생성한 키는 다시 확인할 수 없다. 이 부분은 실제로 한 번 지나가면 재확인이 안 되기 때문에 처음 만들 때 바로 저장해두는 게 맞다.

여기서 느낀 점은, Unity 연동 작업이라고 해서 Unity부터 켜는 게 아니라는 점이었다. 시작은 결국 OpenAI 플랫폼 쪽 준비다. 프로젝트와 키가 먼저 준비되어 있어야 Unity에서 어떤 SDK를 붙여도 의미가 있다. 실제로 이 단계가 빠져 있으면 이후 설정 화면을 다 맞춰도 호출 자체가 안 된다. 그래서 가장 먼저 “키를 안전하게 발급하고 보관하는 단계”를 확실히 끝내는 게 맞았다.

 

---

2. Unity에 OpenUPM 레지스트리 추가

API 키를 준비한 뒤에는 Unity 프로젝트를 만들고 SDK를 설치했다. 이번 문서에서는 Unity에서 OpenAI API를 쓰기 위해 OpenUPM 경로를 통해 패키지를 설치하는 흐름으로 정리되어 있다. 사용한 패키지는 Stephen Hodgson이 공개한 com.openai.unity 오픈소스 기반이며, 작성 당시 기준 버전은 8.8.8로 기록되어 있다. Unity 쪽에서는 Project Settings > Package Manager로 들어가 Scoped Registry를 추가하면 된다. 등록 값은 Name: OpenUPM, URL: https://package.openupm.com, Scope(s): com.openai, com.utilities로 정리되어 있다.

등록이 끝나면 Package Manager의 My Registries 항목 아래에 OpenUPM이 추가된 것을 확인할 수 있고, 여기서 OpenAI 패키지를 설치하면 된다. 문서의 스크린샷도 정확히 이 흐름을 보여준다. Project Settings의 Package Manager에 OpenUPM을 추가하는 장면과, Package Manager 목록에서 OpenAI 패키지가 보이는 화면이 각각 들어가 있다. PDF 이미지까지 같이 보면 이 구간은 블로그에서 설명만 쓰는 것보다 화면 캡처를 붙이는 편이 훨씬 이해가 빠르다.

이 단계는 사실 별것 아닌 것처럼 보이지만, Unity에서 외부 SDK를 붙일 때 자주 막히는 부분이다. 특히 Scoped Registry를 정확히 안 넣으면 Package Manager에 패키지가 안 보이고, 그러면 그 뒤 설명이 다 끊긴다. 개인적으로는 이런 구간이야말로 글에 이미지가 꼭 있어야 한다고 느꼈다. 텍스트로 한 줄 적는 것보다 설정 화면 한 장이 훨씬 빠르다.

---

3. OpenAI Configuration 만들고 API 키 연결

패키지 설치가 끝나면 Project 창에서 OpenAI 패키지를 확인할 수 있고, 이후 OpenAIConfiguration 에셋을 찾거나 새로 만들어야 한다. 문서에서는 이 Configuration에 앞서 발급한 API Key를 붙여 넣는 방식으로 정리되어 있다. 키는 sk-로 시작한다고 명시되어 있고, 실제 Inspector 화면 캡처도 함께 들어 있다. 즉, Unity 프로젝트 안에서는 하드코딩으로 키를 박는 게 아니라 OpenAIConfiguration 자산을 통해 연결하는 흐름이다.

 

이 구조가 좋았던 이유는 테스트 단계에서 관리가 단순하다는 점이다. 코드에서 문자열로 키를 적지 않아도 되고, Inspector에서 Configuration만 연결하면 이후 스크립트에서 OpenAIClient 생성 시 그대로 사용할 수 있다. 실제로 문서의 다음 단계도 이 흐름을 전제로 하고 있다. 코드 안에는 OpenAIConfiguration 필드와 OpenAIClient 필드를 두고, Start()에서 new OpenAIClient(configuration) 형태로 클라이언트를 생성하는 방식으로 이어진다.

여기서는 보안 관점도 같이 생각하게 됐다. 물론 테스트용 프로젝트라고 해도 API 키를 코드에 직접 넣는 습관은 좋지 않다. 특히 Unity 프로젝트는 나중에 팀원과 공유되거나 버전 관리에 올라갈 수 있기 때문에, 초반부터라도 설정 자산으로 분리하는 편이 낫다. 이번 구성은 최소한 테스트 단계에서 그 흐름을 유지할 수 있다는 점이 괜찮았다.

 

---

4. 첫 텍스트 생성 스크립트 작성

기본 세팅이 끝난 뒤에는 텍스트 생성 테스트용 스크립트를 만들었다. 문서에서는 클래스 이름을 OpenAI_Test.cs로 잡고 진행했다. 핵심 필드는 두 개다. 설정값을 받을 OpenAIConfiguration과 연결을 담당할 OpenAIClient다. 이후 Start()에서 클라이언트를 생성하고, Update()에서는 쉽게 테스트할 수 있도록 키보드 입력을 받아 Send()를 호출하는 구조로 작성되어 있다. 기록상으로는 SpaceBar를 눌렀을 때 요청을 보내는 흐름으로 정리되어 있다.

 

OpenAI API를 활용하여 유니티에서 텍스트를 생성하기 위해서 스크립트를 생성합니다.

이름은 자유롭게 지어도 됩니다. 작성자는 OpenAI_Test.cs로 클래스를 생성했습니다.

초기 변수는 설정값을 받을 수 있는 OpenAIConfiguration과 연결을 위한 OpenAIClient 변수를 생성합니다.

이 구조가 좋은 이유는 디버깅이 단순하기 때문이다. UI를 먼저 얹지 않고도, 빈 오브젝트 하나에 스크립트를 붙인 뒤 Play 상태에서 SpaceBar만 눌러 바로 응답을 볼 수 있다. 초기 연동 단계에서는 이런 식의 “최소 동작 경로”가 제일 좋다. 버튼 이벤트나 채팅 UI까지 먼저 만들면 나중에 문제가 생겼을 때 원인이 API인지 UI인지 구분이 어려워진다. 그래서 이번 첫 테스트는 최대한 단순하게 잡는 게 맞았다.

---

5. ChatRequest는 어떻게 구성했는가

실제 요청은 ChatRequest를 생성해서 보냈다. 문서 설명을 보면, 기본 테스트만 할 때는 Message만 있어도 되지만 비용과 직결되기 때문에 비교적 저렴한 모델과 최대 토큰 수를 정해두고 테스트하는 방식으로 작성했다. 사용 예시로는 gpt-4.1-nano 모델과 maxTokens = 256이 들어가 있다. 기록에는 이 모델의 가격도 같이 언급되어 있는데, gpt-4.1-nano는 1M 토큰당 0.1달러로 정리되어 있다. 즉, 단순 테스트에는 가벼운 모델을 먼저 쓰는 방향으로 접근한 셈이다.

이 부분은 개인적으로도 실무 감각이 느껴졌다. 처음 연동한다고 해서 무조건 큰 모델부터 붙일 필요는 없다. 오히려 연결 확인과 역할 테스트, 응답 포맷 확인이 목적이라면 비용이 낮은 모델로 시작하는 게 맞다. 특히 Unity 프로젝트는 테스트를 여러 번 반복하게 되기 때문에, 초반에 비용 감각 없이 붙이면 쌓이는 호출량이 신경 쓰일 수 있다. 이 문서가 처음부터 모델 비용을 같이 언급한 이유도 이해가 갔다.

---

6. Role을 어떻게 이해하면 되는가

이번 텍스트 생성 파트에서 가장 설명 가치가 있는 부분은 Role이었다. 문서에서는 주로 Developer, User, Assistant 세 가지를 사용한다고 정리하고 있다. User는 우리가 일반적으로 챗봇에게 질문할 때 사용하는 역할이다. 즉, 사용자의 실제 프롬프트를 넣는 자리라고 보면 된다. 반면 Developer는 상위 지시를 주는 역할로 설명되어 있다. 예를 들어 “너는 Unity 전문가처럼 대답해야 해” 같은 전역 지침을 넣는 방식이다. 그리고 Assistant는 이전 대화를 참고용으로 넣어 컨텍스트를 이어가기 위한 용도로 쓰인다고 적혀 있다.

문서에 적힌 예시가 꽤 직관적이었다. 만약 Developer에 “무례하고 건방진 톤으로 나를 대해줘” 같은 상위 지시를 넣고, User에서 “친절하게 인사해줘”라고 요청해도 모델은 상위 지시를 따를 가능성이 높다는 식이다. 또 “같은 말을 두 번 하지 마” 같은 지시를 준 뒤, Assistant에 이전 대화를 넣고 User에서 “다시 말해줘”라고 하면, 상위 지시와 이전 대화를 참조한 응답이 나올 수 있다고 설명한다. 즉, 이 문서는 단순히 API 호출만 보여주는 게 아니라 Role이 응답 스타일과 우선순위에 실제로 영향을 준다는 점까지 테스트 포인트로 잡고 있었다.

 Developer의 역할은 상위 지시를 위한 것입니다. 
 우리가 GPT에게 역할을 부여하는 것처럼 (ex) “너는 Unity 전문가처럼 대답해야해.”) 
 상위 지시를 부여할 수 있습니다. 만약 “무례하고 건방진 톤으로 나를 대해줘” 처럼 
 상위지시를 입력했다면, User에서 아무리 “친절하게 인사해줘”라고 프롬프트를 입력해도 
 이 요청은 무시되고 상위 지시를 따라 건방지게 인사합니다.

Assistant의 역할은 이전 대화를 참고용으로 던져주기 위함입니다. 
물론 respon에 담겨 오는 Assistant의 역할은 다르지만 우리가 api를 활용하기 위해 
Role을 지정하고 prompt를 입력하는 행위 자체에는 이전 대화를 입력하기 위한 용도로 사용됩니다. 
상위 지시로 “무례하고 건방진 톤으로 나를 대해줘, 그리고 했던 말을 두번 하지마”라고 학습 시키고
User에서 “다시 말해줘” Assitant에서 이전 대화를 입력했다면 아마 “뭐? 나에게 두번 말하게 하지마.”
라고 답할 확률이 높을 것입니다.

이 부분은 블로그에서 꼭 풀어주는 게 좋다고 느꼈다. 처음 OpenAI API를 붙이는 사람은 대개 “메시지 하나 보내고 답 받는 구조”로만 생각하는데, 실제로는 역할 구분이 들어가면 응답 품질과 제어감이 꽤 달라진다. 특히 Unity 같은 환경에서는 NPC 대사, 툴형 응답, 콘텐츠 생성 어시스턴트 등 역할 기반 설계가 중요해질 수 있어서, 이 개념을 초반에 같이 짚고 넘어가는 편이 낫다.

---

7. 실제 테스트는 어떻게 했는가

문서 기준 마지막 테스트 흐름은 단순하다. Hierarchy 창에 빈 오브젝트를 만들고, 작성한 스크립트를 붙인 뒤, Inspector에서 configuration 변수에 OpenAIConfiguration을 연결한다. 그리고 실행한 뒤 SpaceBar 입력을 주면, Update()에 넣어둔 테스트 코드가 동작하면서 Console Log에 응답이 출력되는 구조다. 프롬프트를 변경해보거나, Role을 다르게 줘가면서 응답이 어떻게 달라지는지 테스트해보기를 권장하는 형태로 마무리되어 있다. 예시로는 “건방져.” 같은 역할 지시도 적혀 있다.

 

이 방식이 좋았던 건, “정말 연결이 됐는가”를 확인하기 위해 불필요한 요소를 최대한 줄였다는 점이다. API 호출 성공 여부, 모델 응답 여부, Role 반영 여부를 Console 하나로 볼 수 있다. 이 정도면 텍스트 생성 첫 단계로는 충분하다. 이후 UI를 붙이거나, 입력 필드와 출력 텍스트를 붙이거나, 대화 기록 관리까지 가는 건 그다음 문제다. 처음에는 이 정도의 최소 테스트가 가장 효율적이었다.

---

8. 이번 단계에서 느낀 점

이번 1편 작업에서 가장 크게 느낀 건, Unity에서 OpenAI API를 붙이는 첫 단계는 생각보다 복잡하지 않다는 점이었다. 오히려 중요한 건 API 키 발급, 패키지 등록, Configuration 연결처럼 기본 세팅을 정확히 끝내는 것이었다. 이게 맞춰지면 텍스트 생성 자체는 비교적 빠르게 확인할 수 있다. 반대로 말하면, 이후 이미지나 음성 기능이 복잡해 보인다고 해도 출발점은 결국 이 세팅을 공유한다는 뜻이다. 그래서 이번 1편을 따로 정리하는 게 의미가 있었다.

 

또 하나는 Role 테스트가 생각보다 재미있었다는 점이다. 단순히 “질문하고 답변 받는 구조”를 넘어서, Developer 지시와 이전 대화 맥락을 어떻게 넣느냐에 따라 응답 성격이 달라진다. 실제 프로젝트에서는 이 부분이 캐릭터성, 답변 톤, 응답 범위 제한 같은 데 바로 연결될 수 있다. 그래서 텍스트 생성 파트는 입문용이면서도 동시에 꽤 중요한 설계 포인트를 담고 있다고 느꼈다.

---

마무리

이번 글에서는 Unity에서 OpenAI API를 쓰기 위한 가장 기본적인 흐름을 정리했다. 먼저 OpenAI 플랫폼에서 secret key를 발급받고, Unity에 OpenUPM 레지스트리를 추가해 OpenAI 패키지를 설치한 뒤, OpenAIConfiguration에 API 키를 연결했다. 그 다음 OpenAI_Test.cs를 만들어 OpenAIClient를 생성하고, ChatRequest를 통해 첫 텍스트 생성 테스트까지 진행했다. 이 정도까지 완료하면 Unity에서 OpenAI API가 정상적으로 연결된 상태라고 볼 수 있다.

 

다음 글에서는 여기서 한 단계 더 가서, 문서에 이어지는 흐름대로 Organization Verification과 이미지 생성 파트를 정리할 예정이다. 그쪽부터는 텍스트 생성보다 변수도 많고, 패키지 한계나 응답 포맷 이슈도 같이 나오기 때문에 따로 끊어서 보는 게 맞다.

---

참고 링크

OpenAI Platform
https://platform.openai.com

OpenAI Platform

 

OpenAI Pricing
https://platform.openai.com/docs/pricing

Pricing | OpenAI API

 

OpenAI Docs Overview
https://platform.openai.com/docs/overview

OpenAI Platform

 

Unity OpenAI SDK (RageAgainstThePixel)
https://github.com/RageAgainstThePixel/com.openai.unity

GitHub - RageAgainstThePixel/com.openai.unity: A Non-Official OpenAI Rest Client for Unity (UPM)

 

OpenAI Libraries
https://platform.openai.com/docs/libraries

 

---

※ 본 글은 직접 테스트하고 정리한 내용을 기반으로 작성했으며, 문서 구조 정리와 문장 다듬기에는 AI를 활용했습니다.