CareerByteCode
ByteBlogby CareerByteCode

Gemini API for Beginners: Your First AI App on Google Cloud

What you build: your first Gemini call from the shell and a small Python app on Cloud Run that asks Gemini on Vertex AI, with no API key, in your own Google Cloud account. Every step tested.

Gemini API for Beginners: Your First AI App on Google Cloud

✍️ Translate this blog into Hindi, Tamil or Telugu

In this lab you talk to Google's Gemini model for the first time: first with one curl command from the shell, then from a small Python web app that you deploy on Cloud Run. The app answers cloud questions like a friendly tutor and shows how many tokens each answer used. There is no API key anywhere: the shell uses your own sign-in and the app uses its own service account. You finish by deleting everything.

Who it is for: beginners who can read a little Python and want to build a first real AI app on Google Cloud. Time: about 1 hour. Cost: a few rupees at most. We made 7 Gemini calls in total, each with under 100 tokens in and out; Gemini Flash-Lite is the smallest and cheapest Gemini model, and Cloud Run and Cloud Build have free monthly limits that this lab stays inside.

Every command below was run for real by the CareerByteCode Team on a fresh Google Cloud project, and every output and screenshot is the real result we got, including two permission problems we met and fixed. We ran the commands from a terminal with the Google Cloud CLI (gcloud, curl, python3); Cloud Shell in your browser has the same tools ready.

🎓⭐ Recommended by CareerByteCode · Live trainingAI Engineering and Agentic AI Programโ‚น35,400See the training →

Part A: Gemini on Google Cloud in plain English

Gemini is Google's family of AI models that read text (and images, audio, video) and write answers. On Google Cloud you reach Gemini through Vertex AI, Google Cloud's AI platform. You pay per token.

How your Gemini app works
You, Cloud Run, the service account, Vertex AI and the answer

Six words you will use in this lab:

  • Model: the trained AI you call. We use gemini-3.5-flash-lite: small, fast and cheap, good for short answers.
  • Prompt: the text you send. The system instruction is a standing rule for every prompt, like "answer in 3 short sentences with one example". Real-life example: the brief you give a new intern on day one.
  • Token: a piece of a word. "virtual machine" is about 2 to 3 tokens. You pay for tokens in (your prompt) and tokens out (the answer), so short prompts and short answers cost less.
  • Temperature: how creative the answer is. 0 is the same answer every time; 1 is more varied. We use 0.4 for clear, steady answers.
  • API key versus service account: an API key is a password string that anyone who finds it can use. A service account is an identity Google gives to your app; it gets only the roles you grant, and there is no secret to leak. That is why this lab uses no key.
  • Global endpoint: Vertex AI serves the newest Gemini models from the global location; Google picks the data centre. In our test, gemini-3.5-flash-lite answered on global and returned "not found" on us-central1 and us-east1.

Before you start

  1. A Google Cloud account (the free trial works) and a project with billing linked. Create one at https://console.cloud.google.com/projectcreate if you do not have one.
  2. Open Cloud Shell (the >_ icon at the top right of the Google Cloud console). It already has gcloud, curl and python3, and it is signed in as you.
  3. Save your project id in a variable. Replace the text in quotes with your own project id:
export PROJECT_ID="your-project-id"

Part B: the lab

Step 1: turn on Vertex AI, Cloud Run and Cloud Build

Why: Vertex AI serves Gemini; Cloud Run runs your app; Cloud Build and Artifact Registry turn your code into a container image for Cloud Run.

gcloud config set project $PROJECT_ID
gcloud services enable aiplatform.googleapis.com run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com
gcloud services list --enabled --filter="name:(aiplatform.googleapis.com OR run.googleapis.com)" --format="value(name)"
Updated property [core/project].
Operation "operations/acat.p2-PROJECT_NUMBER-8c36f3f9-2a6c-42c4-a172-6e05e9d80bf6" finished successfully.
projects/PROJECT_NUMBER/services/aiplatform.googleapis.com
projects/PROJECT_NUMBER/services/run.googleapis.com

Step 2: your first Gemini call from the shell

Why: before writing an app, prove the model answers. request.json holds the prompt and two settings: at most 200 tokens out, temperature 0.4. gcloud auth print-access-token gives a short-lived token for your own sign-in, so there is no key to create or hide. The last line prints the answer and the token counts.

cat > request.json <<EOF
{"contents": [{"role": "user", "parts": [{"text": "Explain what a virtual machine is to a 12 year old, in 2 sentences. Use plain punctuation, no long dashes."}]}],
 "generationConfig": {"maxOutputTokens": 200, "temperature": 0.4}}
EOF
curl -s -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1/projects/$PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash-lite:generateContent" \
  -d @request.json > response.json
python3 -c "import json; r = json.load(open(\"response.json\", encoding=\"utf-8\")); print(r[\"candidates\"][0][\"content\"][\"parts\"][0][\"text\"]); print(\"tokens:\", r[\"usageMetadata\"])"
A virtual machine is a software-based computer that runs inside your regular computer just like an app. It lets you try out different operating systems without needing to buy a whole separate machine.
tokens: {'promptTokenCount': 27, 'candidatesTokenCount': 37, 'totalTokenCount': 64, 'trafficType': 'ON_DEMAND', 'promptTokensDetails': [{'modality': 'TEXT', 'tokenCount': 27}], 'candidatesTokensDetails': [{'modality': 'TEXT', 'tokenCount': 37}]}
APIs and the first call
Steps 1 and 2: the APIs are on and Gemini answers in two sentences

27 tokens in and 37 tokens out. That tiny count is what you pay for. We asked for "plain punctuation, no long dashes" only so the answer prints cleanly in every terminal.

Step 3: write the Python app

Why: a web app lets anyone (with permission) ask questions from a browser or another program. It has three files:

  • requirements.txt: the Python packages: Flask (the web framework), Gunicorn (the web server Cloud Run runs) and google-genai (Google's Gen AI SDK).
  • main.py: the app. genai.Client(vertexai=True, project=..., location="global") means "use Gemini on Vertex AI with the identity I am running as". /ask?q=... sends the question with the tutor system instruction and returns the answer and the token counts as JSON.
  • Procfile: tells Cloud Run how to start the app.
mkdir -p gemini-app && cd gemini-app
cat > requirements.txt <<EOF
flask==3.1.*
gunicorn==23.*
google-genai==1.*
EOF
cat > main.py <<EOF
# A tiny web app that asks Gemini on Vertex AI. No API key: it signs in as the Cloud Run service account.
import os
from flask import Flask, request, jsonify
from google import genai
from google.genai import types

app = Flask(__name__)
client = genai.Client(vertexai=True, project=os.environ["GOOGLE_CLOUD_PROJECT"], location="global")
MODEL = os.environ.get("MODEL", "gemini-3.5-flash-lite")
TUTOR = "You are a friendly cloud tutor for beginners in India. Answer in at most 3 short sentences, with one real-life example. Use plain punctuation, no long dashes."

@app.get("/")
def home():
    return "Gemini app is running. Try /ask?q=your+question\n"

@app.get("/ask")
def ask():
    q = request.args.get("q", "").strip()
    if not q:
        return jsonify(error="add ?q=your question"), 400
    try:
        r = client.models.generate_content(
            model=MODEL, contents=q,
            config=types.GenerateContentConfig(system_instruction=TUTOR, max_output_tokens=300, temperature=0.4))
    except Exception as e:
        return jsonify(error=str(e)[:300]), 502
    u = r.usage_metadata
    return jsonify(model=MODEL, question=q, answer=r.text.strip(),
                   tokens={"in": u.prompt_token_count, "out": u.candidates_token_count})
EOF
cat > Procfile <<EOF
web: gunicorn --bind :\$PORT --workers 1 --threads 4 main:app
EOF
ls -1 && cat main.py | head -12

The first lines of main.py (the full file is in the command above):

Procfile
main.py
requirements.txt
# A tiny web app that asks Gemini on Vertex AI. No API key: it signs in as the Cloud Run service account.
import os
from flask import Flask, request, jsonify
from google import genai
from google.genai import types

app = Flask(__name__)
client = genai.Client(vertexai=True, project=os.environ["GOOGLE_CLOUD_PROJECT"], location="global")
MODEL = os.environ.get("MODEL", "gemini-3.5-flash-lite")
TUTOR = "You are a friendly cloud tutor for beginners in India. Answer in at most 3 short sentences, with one real-life example. Use plain punctuation, no long dashes."

@app.get("/")
The app code
Step 3: the three files and the start of main.py

Step 4: two service accounts, and no roles for the app yet

Why: two identities are involved:

  1. The builder. gcloud run deploy --source . builds your code with Cloud Build, which runs as the project's default Compute Engine service account. In new projects that account has no roles, and our first deploy failed with PERMISSION_DENIED: Build failed because the default service account is missing required IAM permissions. The fix is the Cloud Run Builder role (roles/run.builder) for it.
  2. The app. We create gemini-app for the app itself and on purpose give it no Vertex AI role yet. You will see why in "Break it".
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder" --condition=None --format="value(etag)" > /dev/null && echo "builder role for the source build: granted"
gcloud iam service-accounts create gemini-app --display-name="Gemini tutor app"
until gcloud iam service-accounts describe gemini-app@$PROJECT_ID.iam.gserviceaccount.com > /dev/null 2>&1; do sleep 5; done
echo "service account ready"
Updated IAM policy for project [your-project-id].
builder role for the source build: granted
Created service account [gemini-app].
Service account email: gemini-app@your-project-id.iam.gserviceaccount.com
service account ready

Step 5: deploy to Cloud Run, sign-in required

Why: --no-allow-unauthenticated means only signed-in people with permission can call the app: random visitors cannot spend your Gemini budget. --max-instances=1 caps the app at one copy. --service-account makes the app run as gemini-app.

cd gemini-app
gcloud run deploy gemini-app --source . --region=us-east1 \
  --service-account=gemini-app@$PROJECT_ID.iam.gserviceaccount.com \
  --no-allow-unauthenticated --memory=512Mi --max-instances=1 \
  --set-env-vars=GOOGLE_CLOUD_PROJECT=$PROJECT_ID 2>&1 | tail -4
Done.
Service [gemini-app] revision [gemini-app-00001-b9x] has been deployed and is serving 100 percent of traffic.
Service URL: https://gemini-app-PROJECT_NUMBER.us-east1.run.app
Proxy locally with: gcloud run services proxy gemini-app --region us-east1 --project your-project-id
Accounts and deploy
Steps 4 and 5: the builder role, the app account, and the service is live

Break it and fix it

The app is live, but its service account has no right to use Vertex AI. First we call it with no token, then with your identity token (gcloud auth print-identity-token), which Cloud Run accepts because you own the project.

URL=$(gcloud run services describe gemini-app --region=us-east1 --format="value(status.url)")
echo "without a sign-in token: $(curl -s -o /dev/null -w "HTTP %{http_code}" $URL/)"
curl -s -H "Authorization: Bearer $(gcloud auth print-identity-token)" "$URL/ask?q=What+is+a+region" | python3 -m json.tool
without a sign-in token: HTTP 403
{
    "error": "403 PERMISSION_DENIED. {'error': {'code': 403, 'message': \"Permission 'aiplatform.endpoints.predict' denied on resource '//aiplatform.googleapis.com/projects/your-project-id/locations/global/publishers/google/models/gemini-3.5-flash-lite' (or it may not exist). Remediate access with this Troubles"
}
Break it
No token: HTTP 403 from Cloud Run. With a token: Vertex AI says aiplatform.endpoints.predict denied

Two different "403" answers: the first is Cloud Run refusing a visitor with no sign-in (good, that is what we asked for). The second is Vertex AI refusing the app: Permission 'aiplatform.endpoints.predict' denied. Fix: give gemini-app the Vertex AI User role. New roles take a little time to spread, so the loop asks again every 15 seconds, at most 20 times.

🎓⭐ Recommended by CareerByteCode · Live trainingLearn AI, Build 12+ AI Agentsโ‚น10,620See the training →
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:gemini-app@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user" --condition=None --format="value(etag)" > /dev/null && echo "roles/aiplatform.user granted"
URL=$(gcloud run services describe gemini-app --region=us-east1 --format="value(status.url)")
for i in $(seq 1 20); do
  curl -s -H "Authorization: Bearer $(gcloud auth print-identity-token)" "$URL/ask?q=What+is+a+region" > answer.json
  grep -q "\"answer\"" answer.json && break; sleep 15
done
echo "answered after $i tries"
python3 -m json.tool answer.json
Updated IAM policy for project [your-project-id].
roles/aiplatform.user granted
answered after 6 tries
{
    "answer": "Think of a cloud region as a giant data center building in a specific city, like Mumbai or Chennai. It keeps your apps running fast for local users and safe from power cuts in other cities. For example, hosting your website in the Mumbai region means it loads super quickly for your friends in Delhi.",
    "model": "gemini-3.5-flash-lite",
    "question": "What is a region",
    "tokens": {
        "in": 39,
        "out": 60
    }
}
Fix it
With roles/aiplatform.user the app answers, on the 6th try (about 75 seconds)

The answer came on the 6th try, about 75 seconds after the grant. Notice the answer follows the system instruction: 3 short sentences and a real-life example (Mumbai and Chennai).

POC: three questions, answers and token counts

The proof that the whole app works: three beginner questions, through Cloud Run, to Gemini and back.

URL=$(gcloud run services describe gemini-app --region=us-east1 --format="value(status.url)")
TOKEN=$(gcloud auth print-identity-token)
for q in "What+is+a+Kubernetes+pod" "Why+should+I+delete+cloud+resources+after+a+lab" "What+is+IAM+in+Google+Cloud"; do
  curl -s -H "Authorization: Bearer $TOKEN" "$URL/ask?q=$q" | python3 -c "import json,sys; d = json.load(sys.stdin); print(\"Q:\", d[\"question\"]); print(\"A:\", d[\"answer\"]); print(\"tokens:\", d[\"tokens\"]); print()"
done
Q: What is a Kubernetes pod
A: Think of a Kubernetes pod as a small shipping container that holds your website or app. Just like an auto-rickshaw carries you and your luggage together, a pod groups your application containers so they can work as a team.
tokens: {'in': 40, 'out': 45}

Q: Why should I delete cloud resources after a lab
A: Cloud providers charge you based on how long your resources stay turned on. Deleting them is like turning off the lights and AC when you leave a room so you do not get a surprise electricity bill. Think of it like renting a car, where you return the keys immediately after your drive so you do not keep paying for the parking time.
tokens: {'in': 44, 'out': 68}

Q: What is IAM in Google Cloud
A: Think of IAM as a smart security guard for your Google Cloud projects who checks IDs and gives access. For example, it lets you give your data analyst permission to read sales reports while keeping them away from the billing settings. It simply decides who can do what on your cloud.
tokens: {'in': 41, 'out': 55}
POC
Three answers, each with an Indian real-life example, and 40 to 44 tokens in, 45 to 68 out

Proof: every answer is short, correct and has an everyday example (an auto-rickshaw, switching off the AC, a security guard). Each call used about 40 tokens in and 45 to 68 tokens out. Test quality and cost like this: ask the same few questions after every change to the system instruction, read the answers, and watch the token counts. A shorter instruction and a lower max_output_tokens cut cost directly.

Clean up (delete everything)

Why: a Cloud Run service at zero traffic costs nothing, but the image repository and the source bucket store files, and roles you no longer need are a risk. We delete the service, both roles, the app's account, the image repository and the source bucket.

gcloud run services delete gemini-app --region=us-east1 --quiet 2>&1 | tail -1
gcloud projects remove-iam-policy-binding $PROJECT_ID --member="serviceAccount:gemini-app@$PROJECT_ID.iam.gserviceaccount.com" --role="roles/aiplatform.user" --condition=None --format="value(etag)" > /dev/null && echo "role removed"
gcloud iam service-accounts delete gemini-app@$PROJECT_ID.iam.gserviceaccount.com --quiet 2>&1 | tail -1
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects remove-iam-policy-binding $PROJECT_ID --member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" --role="roles/run.builder" --condition=None --format="value(etag)" > /dev/null && echo "builder role removed"
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet 2>&1 | tail -1
gcloud storage rm -r gs://run-sources-$PROJECT_ID-us-east1 2>&1 | tail -1
echo "Cloud Run services left: $(gcloud run services list --format="value(name)" | wc -l)"
echo "repositories left: $(gcloud artifacts repositories list --location=us-east1 --format="value(name)" | wc -l)"
echo "buckets left: $(gcloud storage buckets list --format="value(name)" | wc -l)"
Deleted service [gemini-app].
Updated IAM policy for project [your-project-id].
role removed
deleted service account [gemini-app@your-project-id.iam.gserviceaccount.com]
Updated IAM policy for project [your-project-id].
builder role removed
Deleted repository [cloud-run-source-deploy].
..........
Cloud Run services left: 0
Listing items under project your-project-id, location us-east1.

repositories left: 0
buckets left: 0
Clean up
0 Cloud Run services, 0 repositories, 0 buckets left

Cloud Run services left: 0, repositories left: 0 and buckets left: 0 are your proof. There was never an API key, so there is no key to delete.

FAQ

Gemini API (AI Studio) or Vertex AI: which one? Both serve Gemini. The Gemini API from Google AI Studio is quick for experiments and uses API keys. Vertex AI uses your Google Cloud project, IAM, service accounts, quotas and billing, which is what companies use in production. The same google-genai SDK works for both: vertexai=True picks Vertex AI.

Can I run the app in Cloud Shell before deploying? The same code can run there, because Cloud Shell signs the SDK in as you. We tested the app only on Cloud Run, so this post shows only the Cloud Run steps.

Why did I get "Publisher model ... was not found"? The model name is wrong, or the model is not served in that location. Use location="global" for the newest Gemini models, and check the name in the Vertex AI Model Garden.

How do I keep cost low? Use Flash-Lite for simple tasks, keep the system instruction short, set max_output_tokens, cache answers you ask often, and keep --max-instances small with sign-in required.

Is my data used to train Google's models? Google Cloud states that Vertex AI does not use your prompts and answers to train its models. Read the Vertex AI data governance page for the details for your account.

Can I make the app public? Yes, with --allow-unauthenticated, but then anyone can spend your budget. Add your own login, a rate limit and a budget alert first.

Why does the first call after deploy take longer? Cloud Run starts a container when a request arrives after a quiet time (a "cold start"). Later calls are fast.

Troubleshooting

You seeWhyFix
Build failed because the default service account is missing required IAM permissionsThe build account has no roles in a new projectGrant roles/run.builder to the Compute default service account (Step 4)
Permission 'aiplatform.endpoints.predict' deniedThe app's account has no Vertex AI role, or it has not spread yetGrant roles/aiplatform.user, wait 1 to 2 minutes
HTTP 403 with no JSON from the app URLCloud Run wants a sign-inSend Authorization: Bearer $(gcloud auth print-identity-token)
Publisher model ... was not found or your project does not have accessWrong model name or locationUse location="global" and an exact model name
Vertex AI API has not been used in projectThe API is offgcloud services enable aiplatform.googleapis.com
Odd characters like รขโ‚ฌโ€ in an answerA file was read with the wrong text encodingOpen files with encoding="utf-8" in Python

What next

Prepared by the CareerByteCode Team from our tested lab, with AI help for the write-up.

Read next →Google Cloud for Absolute Beginners: Projects, Billing and Console⏱ 12 min

⭐ Keep learning with CareerByteCode

Hand-picked to go deeper on this topic
News, guides and updates from the CareerByteCode team
🏅 Contributor writer

The CareerByteCode team writes about what is new on careerbytecode.in: courses, labs, exams, events and the community, which is free to join for influencers and content creators in tech.

Get CareerByteCode Team's next blog by email

One email a week when they publish. Add the weekly Best of ByteBlog too. No spam, unsubscribe with one click.

We email you once to confirm. By subscribing you agree to the privacy policy.

💬 Comments (0)

Top · Newest

Sign in to comment

More from CareerByteCode Team

🎓⭐ Recommended by CareerByteCode · Live trainingAI Engineering and Agentic AI Programโ‚น35,400See the training →