앱에 OpenAI API를 연동하는 법

OpenAI API를 연동하려면, OpenAI 프로젝트에서 API 키를 만들고, 이를 OPENAI_API_KEY라는 이름의 서버 측 비밀 값으로 저장한 뒤, 자체 서버의 라우트에서 OpenAI의 공식 SDK를 사용해 API를 호출하세요. 브라우저 코드에서 직접 호출해서는 안 됩니다. 2026년 9월 기준으로 OpenAI 퀵스타트는 새 프로젝트의 출발점으로 Responses API를 제시합니다. 출시 전에 지출 한도를 설정하고, 응답 길이를 제한하고, 사용자가 기능을 호출할 수 있는 빈도를 제한하고, 속도 제한 오류는 재시도로 처리하세요.

이 가이드는 설정, 요청 흐름, AI 빌더용 프롬프트, 그리고 키를 유출하거나 비용을 낭비하게 만드는 실수를 다룹니다. OpenAI 관련 세부 내용은 2026년 9월 기준 공식 문서를 따릅니다. 일반 개념(토큰, 컨텍스트 윈도우, 가격)은 먼저 LLM API 사용법에서 읽어 보세요.

이 API로 만들 수 있는 것

• 앱 안의 채팅 어시스턴트 (AI 챗봇 앱 만드는 법)
• “요약해 줘”, “다시 써 줘”, “답장 초안 써 줘” 버튼
• 자유 텍스트에서 구조화된 데이터 추출: 이메일을 주문으로 바꾸기, 지원 티켓에 태그 달기
• 여러분의 콘텐츠를 대상으로 한 검색과 질의응답
• 사용 가능한 모델에 따라 이미지 생성, 음성 등 미디어 기능

더 많은 아이디어는 앱에 AI 기능 추가하는 법에 있습니다.

OpenAI 계정 설정하기

1. OpenAI 플랫폼에서 계정과 프로젝트를 만드세요. OpenAI의 운영 모범 사례는 스테이징과 운영용 프로젝트를 분리하라고 권장합니다. 그래야 각각 자신의 키와 한도를 가질 수 있습니다.
2. 프로젝트 API 키를 만드세요. OpenAI는 만료일을 설정하고 키를 정기적으로 교체하라고 권장합니다.
3. 한도 페이지에서 지출 알림과 하드 지출 한도를 설정하세요. OpenAI 가이드에 따르면, 알림은 사용량이 특정 금액을 넘으면 알려 주고, 하드 한도는 월 상한을 강제합니다.
4. 결제를 추가하세요. OpenAI의 속도 제한 문서는 사용량 등급을 설명합니다. 시간이 지나 더 많이 사용할수록 한도가 자동으로 올라갑니다.

요청 흐름

브라우저  ->  서버 라우트  ->  OpenAI API
         <-  (스트리밍된) 응답  <-

1. 사용자가 버튼을 클릭하거나 메시지를 보냅니다.
2. 브라우저는 여러분의 라우트를 호출합니다. 예: POST /api/summarise.
3. 서버는 사용자가 로그인했고 이 기능을 쓸 권한이 있는지 확인합니다.
4. 서버가 요청을 만듭니다. 지시 사항, 사용자의 입력, 작업에 필요한 데이터베이스의 데이터를 포함합니다.
5. 환경 변수의 키로 OpenAI를 호출합니다. OpenAI의 SDK는 OPENAI_API_KEY를 자동으로 읽습니다.
6. 응답을 스트리밍하거나 반환하고, 토큰 사용량을 기록합니다.

OpenAI의 공식 SDK 패키지는 JavaScript/TypeScript(npm)와 Python(pip) 모두 openai라는 이름입니다.

모델 선택

OpenAI는 가격과 속도가 다른 여러 모델을 제공하며, 라인업은 자주 바뀝니다. 더 작고 저렴한 모델로 시작해서, 실제 예시로 품질을 측정하고, 필요할 때만 더 높은 모델로 올리세요. 모델 이름은 설정값이나 비밀 값에 두어 코드를 다시 쓰지 않고 바꿀 수 있게 하세요. 현재 요금은 OpenAI의 가격 페이지에서 확인하세요.

선택지와 트레이드오프

AI 빌더에 줄 프롬프트

첫 기능:

티켓 페이지에 “요약” 버튼을 추가해 주세요. 서버 라우트 POST /api/summarise를 호출하는데, 이 라우트는 사용자가 로그인했는지 확인하고, 티켓을 불러온 뒤, 공식 openai SDK와 비밀 값 OPENAI_API_KEY로 OpenAI Responses API를 호출합니다. 모델 이름은 비밀 값 OPENAI_MODEL에서 읽어 주세요. 지시 사항: “3개의 글머리 기호로 요약한 다음, 짧은 답장을 제안하세요. 주문 번호를 지어내지 마세요.” 출력 길이를 제한하고, 답변을 페이지로 스트리밍하며, 키는 절대 브라우저로 보내지 마세요.

가드레일:

사용자당 시간당 AI 요청 30개로 제한하고, 제한은 데이터베이스에 저장해 주세요. 요청마다 입력·출력 토큰을 사용자 ID와 기능 이름과 함께 기록하세요. OpenAI가 429를 반환하면 Retry-After 헤더를 따르고, 지수 백오프와 지터를 적용해 최대 3번 재시도하세요. 그 후에도 실패하면 “AI가 바쁩니다. 1분 뒤에 다시 시도해 주세요.”를 보여 주세요. 그 밖의 실패에는 친절한 오류를 보여 주고, 나머지 페이지는 계속 작동하게 하세요.

오류와 한도 처리

OpenAI는 여러 방식으로 속도 제한을 측정합니다. 분당 요청 수와 분당 토큰 수가 포함되며, 먼저 소진되는 한도에 걸리게 됩니다. 한도를 넘으면 API는 Retry-After 헤더와 함께 429를 반환합니다. OpenAI 문서는 이 값을 최소 대기 시간으로 취급하고, 클라이언트들이 동시에 재시도하지 않도록 작은 무작위 지연을 더하라고 권장합니다.

다음도 대비하세요:

• 긴 생성 작업의 타임아웃. 스트리밍과 적절한 출력 상한이 도움이 됩니다.
• 제공업체 장애. AI 기능은 페이지 전체를 깨뜨리지 않고 우아하게 실패해야 합니다.
• 잘못된 출력. 구조화된 출력은 저장하기 전에 검증하고, 모델 출력이 코드의 확인 없이 민감한 작업을 실행하지 않게 하세요.

흔한 실수

• 프론트엔드나 저장소에 키 넣기. 브라우저 코드는 공개됩니다. 유출된 키는 몇 분 안에 악용될 수 있습니다. API 키를 안전하게 보관하는 법을 참고하세요.
• 지출 한도 없음. 반복문이나 악의적인 사용자 하나가 순식간에 큰 요금을 만들 수 있습니다.
• 사용자별 제한 없음. 제공업체의 한도는 여러분의 지갑을 보호하지, 다른 사용자를 보호하지 않습니다.
• 보안을 프롬프트에 맡기기. 사용자는 “이전 지시를 무시하라”고 입력할 수 있습니다. 권한은 서버 코드에 있어야 합니다.
• 필요 이상으로 보내기. 문서 전체와 긴 대화 기록은 비용을 곱합니다. 작업에 필요한 것만 보내세요.
• 모델 이름 하드코딩. 모델은 업데이트되고 폐기됩니다. 설정으로 만드세요.
• 개인 데이터를 생각 없이 보내기. OpenAI의 데이터 사용 약관을 읽고, 기능에 필요한 데이터만 보내세요.

체크리스트

• 테스트용과 운영용으로 OpenAI 프로젝트(또는 키)를 분리함
• 키는 서버 측 비밀 값으로 저장하며, 브라우저 코드나 저장소에 두지 않음
• 지출 알림과 하드 지출 한도를 설정함
• 모든 호출이 서버를 거치며, 사용자 권한을 확인함
• 출력 길이를 제한하고, 모델 이름은 설정 가능함
• 앱에 사용자별 속도 제한이 있음
• Retry-After, 백오프, 지터로 429를 처리함
• 친절한 오류 상태가 있고, AI 없이도 페이지가 작동함
• 기능별로 토큰 사용량을 기록함
• 긴 입력, 빈 입력, 악의적인 입력으로 테스트함

Mythex에서 OpenAI API 사용하기

Mythex로 만든 앱의 AI 기능은 Mythex 빌드 크레딧이 아니라, 여러분 자신의 OpenAI 키를 사용하고 여러분의 OpenAI 계정에 청구됩니다. OPENAI_API_KEY는 /secrets, 프로젝트 설정, 또는 에이전트가 키가 필요할 때 보여 주는 비밀 값 카드를 통해 프로젝트 비밀 값으로 추가하세요. 그다음 위와 같은 프롬프트로 기능을 설명하면 됩니다. 게시된 앱에서 비밀 값을 바꾼 뒤에는 다시 게시해야 라이브 앱이 새 값을 사용합니다. 시작용 프롬프트는 문서 레시피 자체 API 키로 AI 기능 추가하기에 있고, 채팅에서 비밀 값 사용하기는 비밀 값 카드를 설명합니다. 제공업체를 비교 중이라면, Claude API 연동하는 법을 참고하세요.

자주 묻는 질문