Gemini Interactions API와 generateContent는 어떻게 선택할까? 4개의 표로 2026년 최신 비교 정리

打开 Gemini 공식 문서를, 특히 Nano Banana 이미지 생성 같은 페이지를 보면 페이지 상단에 새 전환 스위치가 하나 더 생긴 걸 볼 수 있어요. 한쪽은 Interactions API, 다른 한쪽은 generateContent API예요.이건 단순한 문서 개편이 아니에요. Google이 2026년 6월 Interactions API를 GA(정식 사용 가능)로 올리고, 새 프로젝트에는 이 방식을 우선 쓰라고 권장하기 시작했다는 뜻이에요. 이 글에서는 공식 문서와 APIYI 게이트웨이의 실측 결과를 바탕으로, 두 방식의 핵심 차이와 기능 차이, 그리고 실제 호출할 때 어떤 선택을 해야 하는지 한 번에 정리해볼게요.

핵심 가치: 이 글을 읽고 나면 Interactions API와 generateContent의 설계 철학, 상태 관리 방식, 기능 범위 차이를 분명히 이해할 수 있고, APIYI 중계를 통해 Gemini를 호출할 때 어떤 패턴을 선택해야 하는지도 알 수 있어요.

Interactions API 与 generateContent 핵심 차이

먼저 결론부터 말하면, 이 두 API는 단순한 버전 업그레이드 관계가 아니에요. 서로 다른 설계 철학을 가진 두 가지 방식이라고 보는 게 맞아요. generateContent는 상태가 없는 “한 번 요청, 한 번 응답” 방식이라서, 클라이언트가 전체 대화 기록을 직접 관리해야 해요. 반면 Interactions API는 상태 관리를 서버에 맡기고, “Interaction”이라는 새로운 개념을 중심으로 전체 상호작용 방식을 다시 설계했어요.

공식 문서에서는 하나의 Interaction을 “하나의 완전한 대화 또는 작업 턴”으로 정의해요. 내부에는 시간 순서대로 정렬된 여러 실행 단계가 들어가는데, 모델의 사고 과정, 도구 호출과 그 반환 결과, 그리고 최종 모델 출력까지 모두 포함돼요. 즉, Interactions API는 단발성 질답보다 멀티턴 대화나 agent형 작업을 위해 처음부터 설계된 API라고 볼 수 있어요.

이게 왜 중요한지도 여기서 드러나요. Google이 굳이 “정식 사용 가능”이라는 표현을 쓴 건 단순히 기능이 추가됐다는 의미가 아니에요. Interactions API는 2025년 12월에 베타에 들어갔고, 2026년 6월에 GA가 공식 발표됐어요. 공식 블로그에는 “새 프로젝트와 애플리케이션에는 Interactions API 사용을 권장한다”고 명시돼 있고, 공식 문서도 이미 이 새 패러다임을 기본으로 보여주고 있어요. 게다가 Google은 3rd-party SDK와 생태계 파트너들도 이걸 기본 인터페이스로 채택하도록 밀고 있어요. 다시 말해, 이건 선택 가능한 기능 업데이트가 아니라 Gemini 호출 방식을 다시 정의한 변화예요. 다만 개발자들이 자기 속도에 맞춰 옮겨 갈 수 있도록 마이그레이션 가이드를 함께 제공해서, 한 번에 강제 전환시키는 방식은 아니에요.

비교 항목	generateContent（legacy）	Interactions API
현재 상태	레거시지만 완전히 지원됨	2026년 6월부터 정식 GA
공식 권장	기존 프로젝트는 계속 사용 가능	새 프로젝트에는 우선 사용 권장
핵심 메서드	generateContent	interactions.create / get / delete
설계 철학	무상태 단일 요청	Interaction 중심의 상태형 작업 턴
향후 새 기능	계속 주요 모델 지원	최전선 agent 기능이 우선 적용

🎯 기술 제안: APIYI apiyi.com을 통해 Gemini 계열 모델을 호출하고 있다면, 먼저 공식 문서를 기준으로 현재 프로젝트가 어떤 패러다임을 쓰고 있는지 몇 분만 확인해보세요. 그다음에 마이그레이션이 필요한지 판단하는 게 좋아요. 그래야 문서에서 Interactions API가 기본으로 보인다고 해서 기존 코드가 이미 구식이라고 오해하는 일을 피할 수 있어요.

요청 방식과 상태 관리: 두 가지 패러다임의 본질적인 차이

두 방식의 차이를 이해하는 핵심은 “누가 대화 기록을 관리하느냐”예요. generateContent는 클라이언트가 매 요청마다 전체 대화 히스토리 배열을 완전히 다시 붙여 보내야 해요. 10번째 대화라도 앞의 9번 내용을 그대로 함께 실어 보내야 하죠. 방식은 단순하지만, 대화가 길어질수록 요청 본문이 점점 커지고 이전 내용을 반복 전송하게 되어 비용도 늘어요.

Interactions API는 이 문제를 다른 방식으로 풀어요. 이전 호출의 응답에서 받은 interaction id를 다음 요청의 previous_interaction_id로 넣으면, 서버가 전체 대화 기록을 자동으로 불러와요. 클라이언트가 더 이상 수동으로 히스토리를 이어 붙이거나 다시 전송할 필요가 없죠. 공식 문서에는 background=true로 장시간 실행 작업을 돌리는 기능과, “관찰 가능한 실행 단계” 기능도 함께 제공돼요. 덕분에 디버깅하거나 프런트엔드 UI에서 모델의 중간 사고 과정을 보여주기 쉬워서, agent형 제품을 만들 때 특히 유용해요.

다만 서버 측 상태 관리는 공짜가 아니에요. 기본값인 store는 true라서 시스템이 interaction 기록을 보관해요. 유료 계정은 55일, 무료 계정은 1일 보관되죠. 개인정보나 규정 준수가 중요해서 store=false로 저장을 끄면 보관은 막을 수 있지만, 대신 previous_interaction_id로 대화를 이어 가는 기능과 백그라운드 실행 기능도 함께 못 쓰게 돼요. 미리 고민하고 선택해야 하는 지점이에요.

비용 측면에서도 공식은 분명한 장점을 내세워요. 서버가 상태를 유지하면 같은 대화의 기록을 매번 입력 토큰으로 다시 계산하지 않아도 되기 때문에, 캐시 적중률이 눈에 띄게 올라가요. 공식 표현으로는 “더 낮은 비용, 더 높은 캐시 적중률”이에요. 고객센터 챗봇이나 긴 문서 질의응답처럼 많은 맥락을 계속 유지해야 하는 환경에서는 호출량이 늘수록 차이가 꽤 커져요. 반대로 단발성 생성이나 배치 처리처럼 본질적으로 무상태인 작업에서는 이런 이점이 거의 없어요.

또 하나 놓치기 쉬운 점이 있어요. tools, system_instruction, generation_config(thinking_level, temperature 같은 필드 포함)는 “요청마다 따로 설정”하는 값이에요. previous_interaction_id로 이전 대화를 이어 받아도 이런 설정이 자동으로 승계되지는 않아서, 매번 명시적으로 다시 넣어야 해요.

기능 항목	generateContent	Interactions API
대화 기록 관리	클라이언트가 전체 히스토리 수동 병합	서버가 previous_interaction_id로 자동 복원
장시간 작업 백그라운드 실행	미지원	background=true 지원
중간 실행 단계 가시성	직접 파싱 필요	observable execution steps 제공
기록 보관 정책	개념 없음	기본 보관, 유료 55일/무료 1일
도구 및 생성 파라미터 승계	매번 명시적 전달	매번 명시적 전달, 자동 승계 안 됨

💡 선택 팁: 자주 여러 턴을 주고받거나 agent 워크플로를 만드는 프로젝트라면, Interactions API의 상태 관리 방식이 확실히 보일러플레이트 코드를 줄여줘요. 하지만 단일 생성 위주의 호출이라면 이 장점이 크게 체감되지 않을 수 있어요. APIYI apiyi.com 플랫폼에서 먼저 소량으로 비교 테스트해 보고 마이그레이션 여부를 정하는 걸 추천해요.

두 방식의 능력 차이: 무엇은 되고, 무엇은 아직 안 되는가

Interactions API는 새로운 패러다임이지만, 공식 문서에는 아직 지원하지 않는 기능도 분명히 적혀 있어요. 선택할 때는 이 점도 꼭 같이 봐야 해요. “새롭다”는 이유만으로 더 완전하다고 보면 안 되거든요.

공식 문서에 따르면, Interactions API는 현재 비디오 이해에서의 video metadata 필드, Batch API, Python의 automatic function calling, 그리고 explicit caching은 아직 지원하지 않아요. 다만 previous_interaction_id로 구현되는 implicit caching은 가능해요. 반면 generateContent는 스트리밍 출력, 함수 호출, Batch API, explicit caching을 완전 지원하고, 텍스트·이미지·오디오·비디오·문서까지 포함한 전체 멀티모달 입력도 지원해요.

기능	generateContent	Interactions API
Batch API	✅ 지원	❌ 아직 미지원
명시적 캐싱（explicit caching）	✅ 지원	⚠️ 간접 캐시만 지원
비디오 metadata 필드	✅ 지원	❌ 아직 미지원
Python 자동 함수 호출	✅ 지원	❌ 아직 미지원
스트리밍 출력 / 함수 호출	✅ 지원	✅ 지원
비용 및 캐시 적중률	일반 과금	공식상 더 낮은 비용, 더 높은 적중률

Nano Banana 이미지 생성 사례를 보면 두 패러다임의 차이가 가장 직관적으로 드러나요. Interactions API는 interaction.output_image, interaction.output_text 같은 편의 속성으로 마지막에 생성된 이미지나 텍스트 블록을 바로 가져올 수 있어요. 반면 generateContent는 candidates[0].content.parts 배열을 직접 순회하면서 각 part의 타입을 판단해야 해요. 이미 generateContent 파싱 로직이 있는 프로젝트라면, 이 구조 차이 때문에 코드를 꽤 손봐야 할 가능성이 커요. 단순히 endpoint만 바꾸면 끝나는 문제가 아니에요.

이런 기능 차이는 결코 사소하지 않아요. Batch API는 비용에 민감한 프로젝트에서 오프라인 작업을 대량 처리할 때 핵심 수단이에요. 그런데 새 방식으로 옮겼더니 이 기능이 없다면, 전체 배치 처리 파이프라인을 다시 설계해야 할 수도 있죠. explicit caching도 마찬가지예요. 긴 컨텍스트에서 비용을 줄이는 데 직접 연결되는데, 고정된 system prompt나 반복해서 쓰는 참고 자료가 많다면 어떤 내용이 캐시되는지, 얼마나 유지되는지를 세밀하게 제어하지 못하는 건 꽤 큰 제약이에요. 그래서 공식 문서가 두 기술 경로를 함께 남겨둔 거예요. 적어도 이 기능들이 채워지기 전까지는 generateContent가 완전히 대체될 수 없기 때문이죠.

🔧 실무 조언: Batch API로 대량 처리하거나 explicit caching으로 비용을 줄이는 데 크게 의존한다면, 지금 Interactions API로 급하게 옮기면 오히려 기능을 잃을 수 있어요. 생산 환경 코드를 바로 바꾸기보다는 공식 마이그레이션 가이드의 업데이트 속도를 먼저 지켜보는 편이 좋아요.

APIYI网关实测：현재 어떤 패러다임을 써야 할까

결론부터 말하면: 2026년 7월 4일 기준 실측 결과, APIYI 게이트웨이로 Gemini를 호출할 때는 계속 generateContent 원본 형식을 사용하는 게 맞아요.

APIYI 기술팀은 Interactions API의 핵심 경로를 직접 테스트했고, 두 가지 주요 인증 방식까지 모두 확인했어요. 결과는 아래와 같습니다.

테스트 엔드포인트	인증 방식	결과
POST /v1beta2/interactions	Bearer token	❌ 404 (Invalid URL)
POST /v1beta/interactions	Bearer token	❌ 404 (Invalid URL)
POST /v1beta2/interactions	x-goog-api-key header	❌ 404 (Invalid URL)
POST /v1beta/models/{model}:generateContent	Bearer token	✅ 정상 반환

APIYI 공식 문서에는 “APIYI 게이트웨이는 현재 Interactions API 중계를 지원하지 않으며—/v1beta2/interactions와 /v1beta/interactions 경로는 모두 404를 반환한다”라고 적혀 있고, 이어서 “APIYI를 통해 Gemini를 호출할 때는 계속 generateContent 원본 형식을 사용하라”고 명확히 안내하고 있어요. 그래서 APIYI 사이트 내 Gemini 관련 문서도 전부 generateContent 기준으로 통일돼 있습니다. 이렇게 해야 독자가 코드를 복사해서 바로 실행해도 경로 404를 만나지 않거든요.

중요한 건 이 상태가 영구적인 제한이 아니라는 점이에요. Interactions API가 점점 공식 기본 패러다임이 되어가면, 게이트웨이 쪽도 이후에는 지원을 따라올 가능성이 큽니다. 그때는 APIYI도 관련 문서를 업데이트할 거예요. 지금은 docs.apiyi.com/api-capabilities/gemini/interactions-api 페이지를 참고해서 최신 지원 상태를 확인하면 되고, 매번 직접 엔드포인트를 테스트할 필요는 없어요.

이번 테스트는 또 하나의 흔한 오해를 보여줘요. 공식 문서에서 “정식 사용 가능”하다고 해도, 특정 중계 게이트웨이나 서드파티 SDK가 이미 그 방식에 맞게 적응했는지는 전혀 다른 문제예요. 개발자가 공식 문서의 기본 예제를 그대로 가져와 기존 중계 설정에 넣으면, 거의 바로 404를 맞고 나서야 원인을 찾게 되죠. 이런 경우에는 비즈니스 코드부터 의심하기보다, 내 호출 경로가 직결인지 아니면 제3자 중계인지, 그리고 새 패러다임을 지원하는지 먼저 확인하는 게 훨씬 빨라요.

🚀 빠른 시작: 지금 바로 Gemini 호출 경로가 정상인지 확인하고 싶다면, APIYI apiyi.com의 generateContent 형식으로 접속하는 걸 추천해요. 이 플랫폼은 통합 base_url을 제공하고, 텍스트와 이미지 등 다양한 Gemini 모델 호출을 지원해서 인증 세부사항을 따로 처리할 필요가 없어요.

어떻게 선택할까: 시나리오별 결정 가이드

앞의 기능 비교와 실측 결론을 바탕으로, 간단한 시나리오별 추천표를 정리해볼게요.

사용 시나리오	추천 방안	이유
APIYI 게이트웨이로 Gemini 호출	generateContent	현재 게이트웨이는 이 형식만 지원하고, Interactions API 경로는 404를 반환해요
Batch API를 활용한 대량 처리 의존	generateContent	Interactions API는 현재 Batch API를 지원하지 않아요
명시적 캐싱으로 비용 절감 필요	generateContent	Interactions API는 현재 암시적 캐시만 제공해요
멀티턴 대화 agent를 만들고 공식 API에 직결	Interactions API 검토 가능	서버 측 상태 관리로 대화 이력 합치기 로직을 줄일 수 있어요
모델의 중간 실행 단계를 확인하며 디버깅 필요	Interactions API	관찰 가능한 execution step을 기본 지원해요
기존 프로젝트가 이미 generateContent로 잘 동작	당장 마이그레이션 보류	legacy도 계속 지원되고, 단기적으로는 새 모델도 받을 수 있어요

한마디로 말하면, 마이그레이션 여부는 “새로운가 아닌가”가 아니라 Interactions API가 내 의존성을 얼마나 완전히 커버하는지, 그리고 Gemini 호출 경로가 직결인지 중계인지에 따라 달라져요. APIYI를 통해 중계 호출하는 개발자라면 지금은 generateContent를 유지하는 쪽이 가장 안전합니다.

자주 묻는 질문

Q1: generateContent는 종료되나요? 지금 새 프로젝트를 이걸로 개발해도 괜찮을까요?

단기간에는 종료되지 않아요. 공식에서는 generateContent가 legacy로 표시되긴 했지만 “여전히 완전히 지원된다”고 명확히 밝혔고, 가까운 미래에도 새로운 Gemini 주력 모델을 계속 제공할 예정이에요. APIYI apiyi.com을 통해 Gemini를 호출한다면, 지금 시점에서 generateContent를 기반으로 새 프로젝트를 개발해도 전혀 문제 없어요. 문서에 기본으로 Interactions API가 보인다고 해서 너무 걱정할 필요도 없어요.

Q2: APIYI 게이트웨이는 언제 Interactions API를 지원하나요?

현재로선 정확한 일정이 없어요. 이는 해당 패러다임이 공식 생태계에서 얼마나 빠르게 확산되는지, 그리고 게이트웨이 쪽 적응이 얼마나 진행되는지에 따라 달라져요. APIYI apiyi.com 플랫폼의 공식 문서 업데이트를 계속 확인하는 걸 추천해요. Interactions API 중계를 지원하게 되면 관련 문서도 가장 먼저 업데이트될 거예요. 굳이 직접 엔드포인트 상태를 반복해서 테스트할 필요는 없어요.

Q3: 두 API를 같은 프로젝트에서 섞어 써도 되나요?

기술적으로는 호출 경로가 지원하기만 하면 두 패러다임을 함께 사용할 수 있어요. 예를 들어 generateContent로 Batch API의 대량 작업을 처리하면서, 공식 API에 직접 연결한 다중 턴 대화에서는 Interactions API를 시험해볼 수 있어요. 다만 APIYI 게이트웨이를 통해 호출할 때는 현재 Interactions API 경로가 404를 반환하므로, 일단은 generateContent 형식으로 통일하는 걸 권장해요. 같은 프로젝트 안에 서로 다른 두 가지 호출 로직이 섞이면 유지보수 비용이 커질 수 있거든요.

요약

2026년 6월 Interactions API가 정식 전환된 뒤, 이는 분명 Google이 Gemini 호출 방식의 장기적인 방향으로 삼고 있는 형태를 보여줘요. 서버 측 상태 관리나 실행 단계를 관찰할 수 있는 기능은 agent 계열 애플리케이션에 꽤 매력적이에요. 하지만 Batch API, 명시적 캐시, 비디오 metadata 같은 부분에서는 아직 분명한 공백이 있고, generateContent는 여전히 완전히 지원되며 단기간에도 계속 업데이트될 예정이에요. 더 중요한 건, APIYI 게이트웨이를 통해 Gemini를 호출할 때 현재까지의 실측 결과로는 Interactions API 관련 경로가 모두 404를 반환하고, generateContent만 현재 사용할 수 있는 형식이라는 점이에요. Gemini 계열 모델을 안정적으로 호출하려면 APIYI apiyi.com에서 generateContent의 기본 형식으로 접속하는 걸 추천해요. 이후 게이트웨이가 새 패러다임을 지원하면 문서도 즉시 업데이트될 거예요.

이 글의 실측 데이터와 공식 정보 검증은 모두 APIYI 기술팀이 진행했어요. Gemini 계열 모델의 더 자세한 호출 방법이 궁금하다면 APIYI apiyi.com을 통해 기술 지원에 문의해 주세요.

참고 자료

1. Google AI for Developers – Interactions API 개요: Interaction 개념, 핵심 메서드와 기능 설명

   • 링크: ai.google.dev/gemini-api/docs/interactions-overview

2. Google AI for Developers – generateContent（Legacy）: 레거시 API의 지원 상태와 기능 범위

   • 링크: ai.google.dev/gemini-api/docs/interactions

3. APIYI 공식 문서 – Gemini Interactions API 지원 상태: 게이트웨이 실측 엔드포인트 결과와 호출 권장 사항

   • 링크: docs.apiyi.com/api-capabilities/gemini/interactions-api