gcp-sandbox.orgOne Google Cloud service and one hands-on lab a day. Independent; not affiliated with Google.
Monday, October 26, 2026BeginnerAI and ML

Cloud Vision API from Cloud Shell: labels, text and landmarks in four commands

Google's ready-made image models answer simple questions about a picture with no training and no code. Learn what the Vision API does well, where Gemini fits instead, and try it on Google's public sample images.

Cloud Vision API, in plain words

The Cloud Vision API is a set of pre-trained image models behind one endpoint. You send an image (a local file, a gs:// path or a web URL) and name the features you want, and it returns structured JSON: labels such as "Bicycle" with confidence scores, the text it can read, famous landmarks with map coordinates, logos, objects with bounding boxes, dominant colours, crop suggestions and a SafeSearch rating for adult, violent, medical, spoof and racy content.

Nothing to train or host: Google runs the models, and you pay per feature per image. Each feature applied to one image is one billable unit, and the first 1,000 units of each feature every month are free. The gcloud ml vision commands wrap the API, so you can try every feature from Cloud Shell without writing a program.

News from the last two weeks: on October 15, 2026 Google deprecated the emotion labels in face detection. Going forward, FACE_DETECTION returns UNKNOWN for every emotion-related field, so any app that read joy or sorrow ratings from faces needs another approach.

Reach for it when

  • You need cheap, predictable answers to fixed questions at scale, like "does this upload contain text, a logo or explicit content?", with the same JSON shape every time.
  • You want quick OCR on photos of signs, labels or screenshots, or a SafeSearch check before showing user uploads to other people.
  • You're tagging a large image library with labels or landmarks so people can search it, and a per-image price matters more than free-form descriptions.

Skip it when

  • You need open-ended answers about an image, like "what is wrong with this circuit board?" or a caption in your brand's tone. A Gemini model on Gemini Enterprise Agent Platform handles free-form image questions better.
  • You're extracting fields from invoices, forms or IDs into key-value pairs. Document AI is built for structured document parsing; Vision OCR only gives you text and positions.
  • Your labels are specific to your business, like your own product SKUs or defect types. The built-in labels are general, so you'd need a custom model instead.

The AI angle

Vision is the older, specialised side of AI on Google Cloud: fixed tasks, fixed output, low price per image. Gemini models on Gemini Enterprise Agent Platform (formerly Vertex AI) can also read images, but they answer in free text and bill by tokens. A common pattern uses both: Vision filters or tags millions of images cheaply (SafeSearch, OCR, labels), and only the interesting ones go to Gemini for deeper reasoning. Cloud Storage's new object enrichments Preview, covered yesterday, is another way Google now attaches model output to images automatically.

Hands-on lab: Ask the Vision API about three public sample images

Enable the API, run label detection, text detection, landmark detection and SafeSearch on Google's public sample images, optionally try one of your own pictures, then disable the API again.

TIMEAbout 10 minutes
COSTFree: the lab uses about five units spread over four features, and each feature's first 1,000 units a month cost nothing. Past that, most features are $1.50 per 1,000 units. The sample images live in Google's public bucket, so you create no storage.
FREE TIER / CREDITSThe Vision pricing page gives every feature 1,000 free units per month. Billing must be enabled on the project even though this lab stays inside that allowance. Cloud Shell is free.

Before you start

  • A Google Cloud project you own with billing enabled (or the free-trial credit). Use a sandbox project, not a work one.
  • Permission to enable APIs, such as Owner or Service Usage Admin (roles/serviceusage.serviceUsageAdmin).
  • Your project ID, to replace YOUR_PROJECT_ID below.

  1. Open Cloud Shell and enable the API

    Choose Activate Cloud Shell in the console's top bar. Point gcloud at your sandbox project and turn on the Cloud Vision API. Enabling is free; you pay only per image analysed.

    gcloud config set project YOUR_PROJECT_ID
gcloud services enable vision.googleapis.com
SAMPLES=gs://cloud-samples-data/vision

  2. Label an everyday photo

    The sample shows two people cycling in a city. --max-results caps how many labels come back. Each label has a description, a confidence score from 0 to 1, and a topicality score; the grep keeps the output short. Remove it to see the full JSON.

    gcloud ml vision detect-labels $SAMPLES/demo-img.jpg --max-results=5 \
  | grep -E '"(description|score)"'

  3. Read the text on a road sign

    detect-text is the OCR feature for photos with a little text. Its first description is the whole text it read; later entries are single words with their bounding boxes. For dense pages or handwriting, detect-document uses the document OCR feature instead.

    gcloud ml vision detect-text $SAMPLES/ocr/sign.jpg | grep -m1 '"description"'

  4. Name a famous building and find it on a map

    Landmark detection returns the landmark's name, a score and latitude/longitude. Try opening the coordinates in a map to check the answer.

    gcloud ml vision detect-landmarks $SAMPLES/landmark/st_basils.jpeg --max-results=1 \
  | grep -E '"(description|score|latitude|longitude)"'

  5. Run a SafeSearch check

    SafeSearch rates five categories (adult, spoof, medical, violence, racy) on a scale from VERY_UNLIKELY to VERY_LIKELY. This is the feature people use to screen user uploads before showing them to others.

    gcloud ml vision detect-safe-search $SAMPLES/demo-img.jpg

  6. Optional: try a picture of your own

    In Cloud Shell choose More then Upload and pick a photo of an object or place (no people, documents or anything personal). A local file is sent straight to the API; single images can be up to 20 MB. Replace the file name with yours.

    gcloud ml vision detect-labels ./my-photo.jpg --max-results=5 \
  | grep -E '"(description|score)"'

Check that it worked

Step 2 prints five labels with scores, most of them about bikes, cycling or the street scene. Step 3 prints the sign's text. Step 4 should name St. Basil's Cathedral, with coordinates in Moscow. Step 5 shows five categories with likelihoods such as VERY_UNLIKELY. A PERMISSION_DENIED or SERVICE_DISABLED error means the API isn't enabled yet (wait a minute and retry); a billing error means billing isn't linked to the project.

Clean up

The lab created no cloud resources: the images stayed in Google's public sample bucket and nothing was stored in your project. Delete any photo you uploaded to Cloud Shell, then disable the API so nothing can call it by accident. If gcloud refuses because the API was used or enabled recently, add --force, but only in a sandbox where nothing else uses Vision. If this project exists only for practice, you can delete the whole project instead.

rm -f ./my-photo.jpg
gcloud services disable vision.googleapis.com
# if it refuses because the API was just used (sandbox only):
# gcloud services disable vision.googleapis.com --force
# confirm the API is no longer enabled
gcloud services list --enabled | grep vision || echo "Vision API is disabled"
# optional, practice-only project:
# gcloud projects delete YOUR_PROJECT_ID

Gotchas

  • Billing is per feature per image: asking for labels, text and SafeSearch on one picture uses three units, one from each feature's allowance. Request only the features you need.
  • Face emotion ratings are deprecated as of October 15, 2026 and now come back as UNKNOWN. Face detection never identifies who a person is, and celebrity recognition is restricted.
  • A local image is sent base64-encoded inside the request, which grows it by about a third, and the JSON request limit is 10 MB. Put bigger images in Cloud Storage and pass a gs:// path; the per-image limit is 20 MB.
  • Scores are confidence, not truth. Pick a threshold for your use case and test it on your own images, especially for SafeSearch decisions that block or show content.
  • detect-text and detect-document are separate features with separate bills. Use the document one for dense text and handwriting, and the plain one for signs and screenshots.