Nano Banana Pro API 연동 가이드 2026: Vertex AI 와 AI Studio 공식 경로

지금 공식 Nano Banana Pro API를 쓰고 싶다면, 실제 대상 모델은 gemini-3-pro-image-preview 입니다. 별도의 "Nano Banana Pro 개발자 포털"이 따로 있는 것은 아닙니다. 실제로 중요한 공식 경로는 두 가지뿐 입니다. 첫 요청을 가장 빨리 통과시키고 싶다면 Google AI Studio + Gemini Developer API, Cloud IAM, 팀 단위 운영, batch, provisioned throughput 이 중요하다면 Vertex AI를 선택하면 됩니다.

이 차이가 중요한 이유는, 여기서 필요한 답이 이름 확인이 아니라 운영 판단이기 때문입니다. 실제 독자가 알고 싶은 것은 어디서 연결해야 하는지, 어떻게 인증해야 하는지, 지금 이 경로가 무료인지 유료인지, AI Studio 와 Vertex AI 가 같은 일을 하는지 입니다. 가장 짧고 정확한 답은 같은 모델을 둘러싼 서로 다른 운영 계약 이라는 것입니다.

아래의 model ID, Preview 상태, 가격, 과금 경계는 모두 2026년 4월 1일 기준 Google 공식 문서를 다시 확인했습니다.

핵심 요약

실무적으로 한 줄로 줄이면, 가장 중요한 문제가 첫 연결 속도라면 AI Studio, 가장 중요한 문제가 Cloud 운영 통제라면 Vertex AI 입니다.

Nano Banana Pro 공식 API 가 실제로 의미하는 것

먼저 바로잡아야 할 것은 이름에 대한 기대입니다. Nano Banana Pro 는 Gemini 이미지 모델 gemini-3-pro-image-preview 를 가리키며, 별도의 제품 포털을 뜻하지는 않습니다. 현재 상태는 Preview 이고, Google 은 이를 더 복잡한 image generation / editing, 강한 text rendering, 복잡한 layout, 최대 4K 출력에 적합한 상위 route 로 설명합니다.

중요한 점은 surface 가 바뀌어도 모델 자체는 바뀌지 않는다 는 것입니다. AI Studio 에서 쓰는 Nano Banana Pro 와 Vertex AI 에서 쓰는 Nano Banana Pro 는 결국 같은 gemini-3-pro-image-preview 입니다.

Vertex AI 모델 페이지는 또 하나 중요한 뉘앙스를 제공합니다. 모델은 여전히 Preview 이지만, Google 은 고객이 Pre-GA terms 아래에서 production 또는 commercial use 를 선택할 수 있다고 적습니다. 따라서 정확한 해석은 "Preview 라서 무조건 production 금지"도 아니고 "Preview 니까 아무 문제 없음"도 아닙니다. 쓸 수는 있지만 Pre-GA 계약과 변경 가능성을 받아들여야 한다 가 가장 정확합니다.

Nano Banana 계열의 더 넓은 공식 접근 지도를 먼저 보고 싶다면 Nano Banana AI 이미지 생성 API 가이드를, Pro 와 2 중 무엇이 더 맞는지부터 정리하고 싶다면 Nano Banana Pro vs Nano Banana 2를 보세요. 이 글은 그보다 좁게, Pro 에 공식적으로 어떻게 들어가느냐 만 다룹니다.

AI Studio 와 Vertex AI 는 실제로 무엇이 다른가

여기서 중요한 것은 모델 이름보다 어떤 운영 경로를 고르느냐입니다. 둘 다 같은 모델에 도달하지만, 인증 방식, 과금 면, 운영 모델, 확장 방식 이 다릅니다.

AI Studio + Gemini Developer API 는 가장 빠른 공식 경로입니다. Google AI Studio 에서 API key 를 만들고, 필요하면 공식 UI 에서 prompt 를 먼저 시험한 뒤, 그대로 Gemini Developer API 로 코드에서 모델을 호출하면 됩니다. 개인 개발, 프로토타입, 소규모 팀의 초기 통합에는 이 경로가 가장 합리적입니다.

Vertex AI 는 Nano Banana Pro 가 단순 실험이 아니라 실제 Cloud workload 의 일부가 되었을 때 더 적합합니다. IAM, project governance, application default credentials, batch, provisioned capacity 가 중요해지는 순간 Vertex 는 "더 복잡한 대안"이 아니라 "맞는 운영 환경"이 됩니다. Google 이 Vertex AI 모델 페이지에서 Standard PayGo, Flex PayGo, Batch prediction, Provisioned Throughput 을 명시하는 것도 바로 그 이유를 보여줍니다.

가장 짧은 판단 규칙은 이렇습니다.

• 지금 중요한 것이 developer velocity 라면 AI Studio
• 지금 중요한 것이 Cloud operations 와 governance 라면 Vertex AI

경로 1: AI Studio + Gemini Developer API

많은 독자에게 이 경로가 맞는 시작점입니다. Google AI Studio 는 Gemini Developer API key 관리와 실험 흐름의 중심입니다. 단순 playground 가 아니라 공식 API-key 경로의 일부 로 보는 것이 정확합니다.

여기서 가장 큰 오해가 발생합니다. AI Studio 를 열어 보고 시험할 수 있다는 사실 때문에 Nano Banana Pro 에도 무료 API 층이 있을 것처럼 느끼는 경우입니다. 하지만 공식 pricing page 는 분명합니다. gemini-3-pro-image-preview 에는 Free Tier: Not available 라고 적혀 있습니다. Billing FAQ 도 더 정확하게 말합니다. AI Studio 자체는 무료로 쓸 수 있지만, paid features 에 paid API key 를 연결하는 순간 그 key 의 usage 는 과금된다 는 것입니다.

안전한 해석은 다음과 같습니다.

• AI Studio 라는 UI 자체는 무료로 열어 쓸 수 있다
• Nano Banana Pro 의 API 사용 계약은 여전히 유료
• "AI Studio 에서 보인다"는 사실은 "무료 Pro API 가 있다"는 뜻이 아니다

이 경로가 맞는 경우

다음과 같다면 먼저 AI Studio 입니다.

• 첫 working request 를 가장 빨리 보내고 싶다
• 현재 단계에서는 API key 로 충분하다
• prompt 와 output style 을 계속 반복하고 있다
• 아직 Cloud IAM, batch, provisioned throughput 이 필요하지 않다

최소 JavaScript 예제

먼저 공식 SDK 를 설치합니다.

bash
npm install @google/genai

그 다음 API key 로 요청합니다.

javascript
import { GoogleGenAI } from "@google/genai";
import fs from "node:fs";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: "gemini-3-pro-image-preview",
  contents: "Create a clean product hero image for a mechanical keyboard on a dark studio background.",
  config: {
    responseModalities: ["IMAGE"],
    imageConfig: {
      aspectRatio: "16:9",
      imageSize: "2K",
    },
  },
});

for (const part of response.candidates[0].content.parts) {
  if (part.inlineData) {
    fs.writeFileSync(
      "nano-banana-pro-output.png",
      Buffer.from(part.inlineData.data, "base64"),
    );
  }
}

이것이 가장 짧은 공식 경로입니다. AI Studio 에서 key 를 만들고 GEMINI_API_KEY 를 설정한 뒤 generateContent 를 호출하면 됩니다. 현재 image-generation docs 에는 작지만 실무적으로 중요한 주의사항도 있습니다. 1K, 2K, 4K 의 K 는 반드시 대문자여야 합니다.

REST 로 먼저 확인하고 싶다면 Gemini Developer API 와 x-goog-api-key 인증으로 같은 계약을 그대로 사용할 수 있습니다. 바뀌는 것은 transport 이지 route 의 본질이 아닙니다.

경로 2: Vertex AI 는 통제된 Cloud 운영을 위한 선택

문제가 "어떻게 가장 빨리 붙일까"에서 "이것을 Cloud 안에서 어떻게 운영할까"로 바뀌는 순간 Vertex AI 가 더 자연스러운 선택이 됩니다. Vertex 는 단지 더 무거운 껍데기가 아니라, Cloud 인증과 운영 계약 자체가 가치 인 경로입니다.

Gemini Developer API 경로의 중심은 API key 입니다. Vertex AI 경로의 중심은 Cloud auth 입니다. Google 의 현재 image-generation docs 는 GenAI SDK 를 GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, GOOGLE_GENAI_USE_VERTEXAI=True 로 설정하는 방식을 보여줍니다. 이것만으로도 지금 있는 곳이 단순 API-key 경로가 아니라 Google Cloud operating model 이라는 점이 분명해집니다.

이 경로가 맞는 경우

다음과 같다면 Vertex 를 택하는 편이 낫습니다.

• 개인 실험이 아니라 팀 앱이다
• IAM, 감사, project governance 가 필요하다
• batch 또는 provisioned throughput 이 필요하다
• API key 배포보다 service account / ADC 가 더 안전하다
• 단순 호출보다 장기 운영이 더 큰 문제다

최소 Node.js 예제

같은 SDK 를 설치합니다.

bash
npm install @google/genai

그 다음 Google 의 Vertex docs 에 나온 환경 변수를 설정합니다.

bash
export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

이후 같은 모델을 Vertex 에서 호출합니다.

javascript
import fs from "node:fs";
import { GoogleGenAI, Modality } from "@google/genai";

const client = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION || "global",
});

const response = await client.models.generateContent({
  model: "gemini-3-pro-image-preview",
  contents:
    "Create a premium launch poster for a smart watch, crisp typography, dark editorial lighting.",
  config: {
    responseModalities: [Modality.IMAGE],
  },
});

for (const part of response.candidates[0].content.parts) {
  if (part.inlineData) {
    fs.writeFileSync(
      "vertex-nano-banana-pro-output.png",
      Buffer.from(part.inlineData.data, "base64"),
    );
  }
}

여기서 바뀌지 않은 것 은 model string 이고, 바뀐 것 은 client setup 과 auth assumptions 입니다. 기사 전체를 코드로 요약하면 이 차이 하나가 핵심입니다.

가격, Preview, 그리고 가장 흔한 계약 오해

Google 의 pricing pages 는 이 부분을 꽤 명확하게 보여 줍니다. Gemini Developer API pricing 에서 gemini-3-pro-image-preview 는 무료 API tier 가 없고, image output 은 1K/2K 당 0.134 달러, 4K 당 0.24 달러 입니다. Vertex AI pricing 에서는 Standard 가 거의 같은 per-image 비용으로 계산되고, Flex/Batch 는 그것을 1K/2K 는 0.067 달러, 4K 는 0.12 달러 로 낮춥니다.

이 사실에서 두 가지 실용적인 결론이 나옵니다.

• AI Studio 가 더 가볍다고 해서 자동으로 더 싼 것은 아니다
• Vertex AI 가 Cloud 안에 있다고 해서 자동으로 더 비싼 것도 아니다

차이를 만드는 핵심은 운영 계약입니다. AI Studio 는 API key 기반의 빠른 시작을 위해 최적화되어 있고, Vertex AI 는 Cloud-native 운영과 확장을 위해 최적화되어 있습니다.

그리고 다시 한번 강조해야 할 점이 있습니다. AI Studio 를 무료로 열어볼 수 있다는 사실이 Nano Banana Pro API 가 무료라는 뜻은 아닙니다. Billing FAQ 의 정확한 읽기는 이렇습니다. AI Studio 자체는 paid API key 를 paid features 에 연결하기 전까지 무료로 쓸 수 있지만, Nano Banana Pro 같은 경로의 실제 API usage 는 과금된다.

AI Studio 에서 시작해서 나중에 Vertex 로 옮길 수 있을까

네, 그리고 많은 팀에게 그 순서가 가장 합리적입니다. AI Studio 에서 prompt 와 출력 품질을 먼저 이해하고 첫 integration 을 통과시킨 뒤, 실제로 Cloud-native control 이 필요해졌을 때 Vertex AI 로 옮기면 됩니다.

이 이전이 생각보다 가벼운 이유는 모델의 identity 가 변하지 않기 때문 입니다. 바뀌는 것은 주변 계약입니다.

• API key auth 에서 Cloud auth 로
• AI Studio 쪽 key / project 관리에서 Cloud project / IAM 운영으로
• "먼저 연결"에서 "지속적으로 운영"으로

그래서 모든 실험을 처음부터 Vertex AI 에 넣는 것도 과하고, 반대로 AI Studio 경로를 영구적인 최종형처럼 보는 것도 종종 틀립니다. 정답은 오늘의 운영 부담이 어디에 있는지에 달려 있습니다.

30초 안에 결정하기

정말 짧은 판단 규칙만 원한다면 이것이면 충분합니다.

다음이 진짜 질문이라면 AI Studio + Gemini Developer API 입니다.

• "가장 빨리 첫 요청을 보내려면?"
• "공식 환경에서 prompt 를 먼저 확인하고 싶다"
• "Cloud 운영을 전부 도입하기 전에 공식 route 로 먼저 붙이고 싶다"

다음이 진짜 질문이라면 Vertex AI 입니다.

• "이것을 우리 Google Cloud 안에 어떻게 넣을까?"
• "API key 배포 대신 팀에 통제된 access 를 어떻게 줄까?"
• "batch 나 provisioned throughput 을 어떻게 계획할까?"

그리고 진짜 고민이 route 가 아니라 Pro 라는 모델 자체가 필요한지 여부 라면, 먼저 입구에서 시간을 쓰지 않는 편이 낫습니다. Nano Banana Pro vs Nano Banana 2를 먼저 보세요. 많은 workload 에서는 더 큰 비용 / 아키텍처 차이가 route 선택이 아니라 model choice 쪽에 있습니다.