Cloud Vision API (Vision AI)AuthorCloudBrum editorial teamLast reviewed31 Oct 2026Reading time~12 minLevelBeginner to advanced

• Label detectionBroad categories for the whole picture, such as "Street", "Bicycle" or "Wedding", each with a score between 0 and 1. A starting point for search and tagging.
• Object localizationFinds individual objects and gives each a name, a score and a normalised bounding box, so you can draw it or crop to it.
• Text and document text detectionTEXT_DETECTION reads sparse text such as signs and labels. DOCUMENT_TEXT_DETECTION is built for dense pages and handwriting and returns pages, blocks, paragraphs, words and symbols.
• SafeSearchRates a picture for adult, violent, racy, medical and spoof content on a five-step scale from VERY_UNLIKELY to VERY_LIKELY. You choose where the lines go.
• Landmarks, logos and web detectionNames well-known places and brands, and finds the same or similar pictures on the web with the pages that use them. Useful for rights checks and reverse image search.
• Face detectionLocates faces and returns landmarks, angles and likelihoods for expressions and headwear. It does not say whose face it is, and there is no face collection.
• Image properties and crop hintsDominant colours for design and filtering, and suggested crops for the aspect ratios you give.
• Batch and asynchronous jobsUp to 16 images go in one request. PDFs, TIFFs and big image sets are processed as offline jobs that write JSON files to a Cloud Storage bucket.

images:annotate

The main REST method. A request holds up to 16 image requests, each with an image and a list of features.

Feature

One kind of analysis, such as LABEL_DETECTION. You can list several for one image, and each is billed.

Unit

The billing count. One feature applied to one image is one unit. Two features on one picture are two.

Image source

Either the bytes of the picture (base64 in JSON) or a gs:// or public URL for the API to fetch.

Likelihood

SafeSearch and face answers come as UNKNOWN, VERY_UNLIKELY, UNLIKELY, POSSIBLE, LIKELY or VERY_LIKELY, not as a number.

Normalised vertices

Bounding boxes given as fractions of the width and height, so they are independent of the resolution.

TEXT_DETECTION

OCR tuned for a little text inside a bigger scene.

DOCUMENT_TEXT_DETECTION

OCR tuned for dense text and handwriting, with the page structure kept.

Web detection

A feature that finds web entities, matching pages and visually similar images for a picture.

Product Search

A separate part of the API that matches a photo against a catalogue of reference images you upload.

Asynchronous batch

Offline jobs (files:asyncBatchAnnotate for PDF and TIFF files of up to 2,000 pages) that read from and write to Cloud Storage and return an operation to poll. API keys are not accepted for this method, so use a service account.

Application Default Credentials

The way Google client libraries find credentials: the attached service account on Google Cloud, or your gcloud login on a laptop.

Service account

A non-human identity the application runs as. It needs read access to the bucket and the right to use the project’s APIs.

API key

A simple credential that can be restricted to the Vision API. Convenient, but a service account is the safer default.

Document AI

Google’s service for forms, invoices and other structured documents. Use it where OCR is only the first step.

Enable the Vision API and screen pictures in a bucket with the gcloud CLI

1. Decide what you want backLabels, text, a safety rating, or a sentence? The first three are Vision. A sentence or an answer about the picture is a job for Gemini, and a structured invoice is a job for Document AI.
2. Create a project and set a budgetUse a project of its own so usage and cost are easy to read. Add a budget alert before the first call, because every feature on every image is billed after the free units.
3. Enable the APIRun gcloud services enable vision.googleapis.com. You need the Service Usage Admin role or an owner of the project to do it.
4. Create a service account for the applicationGive it read access to the one bucket that holds the pictures. Don’t download a key file. On Cloud Run, Cloud Functions or GKE, attach the service account and let Application Default Credentials find it.
5. Try each feature from the command linegcloud ml vision detect-labels, detect-text, detect-safe-search and the others take a local file or a gs:// address. Run them on your own pictures.
6. Pick thresholds from a sampleDecide which SafeSearch levels reject, which go to a person and which pass. Choose a minimum label score. Note the date, since models change.
7. Batch and count unitsSend up to 16 images per call and compute the units before a big run: images times features.
8. Run PDFs and TIFFs as jobsUse the asynchronous batch method with an output bucket, then read the JSON files. Poll the operation instead of holding a connection.
9. Watch quota, errors and spendLook at the API dashboard for the request rate and errors, keep an alert on the budget, and re-run your sample every few months.

• Put up to 16 images in each request instead of one call per picture.
• Use gs:// addresses when the pictures are already in Cloud Storage, so you don’t pay to base64 them through your own server.
• List just the features you act on. Every extra one adds time and units.
• Run offline PDF and TIFF work as asynchronous jobs and poll the operation.
• Keep your workers in the same Region as the bucket to cut transfer time.
• Resize large photos first. Most features work well at a couple of thousand pixels on the long side.
• Use retries with backoff and jitter for 429 and 5xx answers.
• Keep the answer for each image hash and reuse it, so a repeat upload does no new work.

FinOps is the habit of managing cloud spend together with engineering. These are the FinOps checks that matter most for Cloud Vision API.

• Remember the unit rule: images times features. Compute it before a batch.
• Use the free 1,000 units per feature each month for development, not for a production plan.
• Ask for SafeSearch together with label detection if Google’s pricing page still lists it as free in that combination for your account.
• Deduplicate and cache before calling the API.
• Don’t request TEXT_DETECTION and DOCUMENT_TEXT_DETECTION for the same picture. They are separate features, so you pay for both.
• Set a budget alert on the project with thresholds at 50, 80 and 100 percent.
• Check the volume tiers; rates fall after a monthly threshold per feature.
• Delete test projects and old keys.

• Run the application as a service account with read access to one bucket, and no downloaded key file.
• Use Application Default Credentials. On Google Cloud, attach the service account to the runtime.
• If you must use an API key, restrict it to the Vision API and to your callers, and rotate it.
• Turn on public access prevention and uniform bucket-level access on the bucket.
• Delete pictures with a lifecycle rule and turn off soft delete if the pictures are personal.
• Check whether VPC Service Controls support your setup, and read its limits for the Vision API.
• Enable audit logging for the calls that your policy needs to record, where Google Cloud offers it.
• Use customer-managed encryption keys on the bucket if your rules call for them.
• Review the data processing terms and the notes on location before sending customer pictures.
• Give the billing alert an owner who will look at it.

Cloud Audit Logs record who changed the configuration, Cloud Asset Inventory keeps the history of resources such as buckets and keys, and Security Command Center flags risky settings. Google runs the models. Everything about the content is on your side: which pictures go in, how long they stay and what the answers trigger.

• Cache results and skip duplicates.
• Smaller pictures mean less data moved.
• Ask only for the features you use.
• Delete test projects and old pictures.
• Choose a bucket Region with a lower carbon footprint where your data rules allow it, and use the Carbon Footprint report for the project’s totals.
• Google’s report works by project and service group, so quote no Vision figure of your own.

Purchase options

What you actually pay for

• Units: one per feature per image, after the free allowance
• Lower rates after a monthly volume threshold, per feature
• Cloud Storage for the pictures and for batch output
• Network egress, if the pictures or results leave Google Cloud
• Separate meters for Document AI, Video Intelligence, Product Search and Gemini

The API switched on for one project, a service account that can read a single private bucket, a bucket that deletes pictures after 30 days and a budget alert. The CLI tab enables the API, tries each feature, runs a PDF job and makes the same call as REST. Terraform describes the project pieces. The Python tab screens a list of gs:// pictures in batches of 16 with labels and SafeSearch, keeps one bad picture from failing the batch, and reads sparse or dense text. The C# tab does the same screening over a bucket and prints how many units the run used. Replace the project, bucket and names with your own.

# Placeholders: replace the project, the bucket and the object names.
PROJECT=my-project-id
BUCKET=my-image-intake
SA=vision-app
BILLING_ACCOUNT=000000-AAAAAA-BBBBBB

gcloud config set project $PROJECT

# 1. Turn the API on and create the identity the application will run as. The caller needs permission to use the project's APIs.
gcloud services enable vision.googleapis.com
gcloud iam service-accounts create $SA --display-name="Image intake (Vision API)"
gcloud storage buckets add-iam-policy-binding gs://$BUCKET \
  --member="serviceAccount:$SA@$PROJECT.iam.gserviceaccount.com" --role="roles/storage.objectViewer"

# 2. Try each feature from the command line. A local path or a gs:// URL both work.
gcloud ml vision detect-labels gs://$BUCKET/uploads/shopfront.jpg --max-results=10
gcloud ml vision detect-safe-search gs://$BUCKET/uploads/shopfront.jpg
gcloud ml vision detect-text gs://$BUCKET/uploads/shopfront.jpg --language-hints=en,hi
gcloud ml vision detect-document gs://$BUCKET/uploads/invoice.png
gcloud ml vision detect-objects gs://$BUCKET/uploads/shopfront.jpg
gcloud ml vision suggest-crop gs://$BUCKET/uploads/shopfront.jpg --aspect-ratios=1:1,16:9

# 3. Text from a multi-page PDF is an offline job: the result is written to Cloud Storage as JSON.
gcloud ml vision detect-text-pdf gs://$BUCKET/uploads/contract.pdf gs://$BUCKET/results/contract-

# 4. The same call as REST, which is what every client library sends. Two features in one request are billed as two units per image.
curl -s -X POST "https://vision.googleapis.com/v1/images:annotate" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-user-project: $PROJECT" -H "Content-Type: application/json" \
  -d '{"requests":[{"image":{"source":{"imageUri":"gs://'$BUCKET'/uploads/shopfront.jpg"}},
       "features":[{"type":"LABEL_DETECTION","maxResults":10},{"type":"SAFE_SEARCH_DETECTION"}]}]}'

# 5. Cap the damage of a runaway client: a budget alert on the project, and a look at API usage.
gcloud billing budgets create --billing-account=$BILLING_ACCOUNT --display-name="vision-monthly" \
  --budget-amount=50USD --filter-projects=projects/$PROJECT --threshold-rule=percent=0.8 --threshold-rule=percent=1.0
gcloud services list --enabled --filter="config.name:vision.googleapis.com"

# 6. Switch the API off again when the project ends.
gcloud services disable vision.googleapis.com

# Cloud Vision API for one project: the API switched on, a service account that can only read one bucket, a private bucket and a budget alert.
terraform {
  required_providers {
    google = { source = "hashicorp/google", version = ">= 6.0" }
  }
}

variable "project_id" {
  type = string
}

variable "billing_account" {
  description = "Billing account ID, for example 000000-AAAAAA-BBBBBB"
  type        = string
}

provider "google" {
  project = var.project_id
  region  = "asia-south1"
}

data "google_project" "this" {}

resource "google_project_service" "vision" {
  service            = "vision.googleapis.com"
  disable_on_destroy = false
}

resource "google_service_account" "app" {
  account_id   = "vision-app"
  display_name = "Image intake (Vision API)"
}

resource "google_storage_bucket" "images" {
  name                        = "my-image-intake-${var.project_id}"
  location                    = "ASIA-SOUTH1"
  uniform_bucket_level_access = true
  public_access_prevention    = "enforced"

  # Deleted pictures would otherwise stay recoverable for the default soft-delete period.
  soft_delete_policy {
    retention_duration_seconds = 0
  }

  # Uploads vanish after a month, so pictures of people do not pile up.
  lifecycle_rule {
    condition { age = 30 }
    action { type = "Delete" }
  }
}

# The application reads uploads and nothing else. Vision reads a gs:// picture with the caller's own access, so this bucket role is what lets the call work.
resource "google_storage_bucket_iam_member" "app_reads" {
  bucket = google_storage_bucket.images.name
  role   = "roles/storage.objectViewer"
  member = "serviceAccount:${google_service_account.app.email}"
}

# An alert at 80 and 100 percent of a monthly amount for the whole project. A budget only notifies; it does not stop spending.
resource "google_billing_budget" "vision" {
  billing_account = var.billing_account
  display_name    = "vision-monthly"

  budget_filter {
    projects = ["projects/${data.google_project.this.number}"]
  }

  amount {
    specified_amount {
      currency_code = "USD"
      units         = "50"
    }
  }

  threshold_rules { threshold_percent = 0.8 }
  threshold_rules { threshold_percent = 1.0 }
}

"""Screening and reading pictures with the Cloud Vision API (google-cloud-vision). Pictures stay in Cloud Storage and are referenced by gs:// URL."""
from google.cloud import vision

F = vision.Feature.Type
Likelihood = vision.Likelihood
MAX_PER_REQUEST = 16          # the API accepts up to 16 images in one images:annotate call


def image_from(uri):
    return vision.Image(source=vision.ImageSource(image_uri=uri))


def units(image_count, feature_count):
    """What a batch will bill: every feature on every image is one unit. Check this before a big run, because 1,000 units a month per feature are free and the rest are not."""
    return image_count * feature_count


def judge(safe):
    """'reject', 'review' or 'allow' from a SafeSearchAnnotation. Adult and violent content are strict; 'racy' only goes to a person."""
    strict = max(safe.adult, safe.violence)
    if strict >= Likelihood.LIKELY:
        return "reject"
    if strict == Likelihood.POSSIBLE or safe.racy >= Likelihood.LIKELY:
        return "review"
    return "allow"


def screen(client, uris):
    """Labels and SafeSearch for many pictures. Returns {uri: result}. One bad picture fails alone: its entry carries the error and the rest of the batch is fine."""
    features = [vision.Feature(type_=F.LABEL_DETECTION, max_results=10), vision.Feature(type_=F.SAFE_SEARCH_DETECTION)]
    out = {}
    for start in range(0, len(uris), MAX_PER_REQUEST):
        chunk = uris[start:start + MAX_PER_REQUEST]
        reply = client.batch_annotate_images(requests=[vision.AnnotateImageRequest(image=image_from(u), features=features) for u in chunk])
        for uri, resp in zip(chunk, reply.responses):
            if resp.error.code:
                out[uri] = {"error": resp.error.message}
                continue
            out[uri] = {"decision": judge(resp.safe_search_annotation),
                        "labels": [(l.description, round(l.score, 2)) for l in resp.label_annotations if l.score >= 0.8]}
    return out


def read_text(client, uri, dense=False):
    """TEXT_DETECTION suits a sign or a label inside a photo. DOCUMENT_TEXT_DETECTION suits pages, tables and handwriting and keeps the layout."""
    feature = vision.Feature(type_=F.DOCUMENT_TEXT_DETECTION if dense else F.TEXT_DETECTION)
    resp = client.annotate_image(vision.AnnotateImageRequest(image=image_from(uri), features=[feature]))
    if resp.error.code:
        raise RuntimeError(resp.error.message)
    if dense:
        return resp.full_text_annotation.text
    return resp.text_annotations[0].description if resp.text_annotations else ""


if __name__ == "__main__":
    # Application Default Credentials: the service account on Cloud Run, or `gcloud auth application-default login` on a laptop.
    client = vision.ImageAnnotatorClient()
    print(screen(client, ["gs://my-image-intake/uploads/shopfront.jpg"]))

// Screen pictures in a Cloud Storage bucket with SafeSearch and labels, in batches, and print how many billable units the run used.
// Uses Application Default Credentials; the account needs read access to the bucket and permission to use the Vision API in the project.
using Google.Cloud.Storage.V1;
using Google.Cloud.Vision.V1;

const string bucket = "my-image-intake";
const int perRequest = 16;                     // the API accepts up to 16 images in one call

var storage = await StorageClient.CreateAsync();
var vision = await ImageAnnotatorClient.CreateAsync();

var names = storage.ListObjects(bucket, "uploads/")
    .Where(o => o.Name.EndsWith(".jpg", StringComparison.OrdinalIgnoreCase) || o.Name.EndsWith(".png", StringComparison.OrdinalIgnoreCase))
    .Select(o => o.Name).ToList();

var features = new[] { new Feature { Type = Feature.Types.Type.LabelDetection, MaxResults = 10 }, new Feature { Type = Feature.Types.Type.SafeSearchDetection } };
var units = 0;
var held = 0;

foreach (var chunk in names.Chunk(perRequest))
{
    var requests = chunk.Select(name => new AnnotateImageRequest
    {
        Image = Image.FromUri($"gs://{bucket}/{name}"),
        Features = { features }
    });
    var reply = await vision.BatchAnnotateImagesAsync(requests);
    units += chunk.Length * features.Length;   // every feature on every image is one unit

    for (var i = 0; i < chunk.Length; i++)
    {
        var r = reply.Responses[i];
        if (r.Error != null)                   // one bad picture does not fail the batch
        {
            Console.WriteLine($"{chunk[i],-40} error: {r.Error.Message}");
            continue;
        }
        var safe = r.SafeSearchAnnotation;
        var worst = (Likelihood)Math.Max((int)safe.Adult, (int)safe.Violence);
        var verdict = worst >= Likelihood.Likely ? "reject" : worst == Likelihood.Possible || safe.Racy >= Likelihood.Likely ? "review" : "allow";
        if (verdict != "allow") held++;
        var labels = string.Join(", ", r.LabelAnnotations.Where(l => l.Score >= 0.8f).Select(l => l.Description));
        Console.WriteLine($"{chunk[i],-40} {verdict,-7} {labels}");
    }
}

Console.WriteLine($"{names.Count} picture(s), {units} billable unit(s), {held} held back");

Videos picked for this service. Each one is labelled with its source, opens on YouTube if you prefer, and loads only when you press play.

Typical callers are Cloud Run functions or Cloud Run services triggered by new objects in Cloud Storage, with results saved to Firestore or BigQuery and routed on with Eventarc. Request counts, errors and quota show up in Cloud Monitoring.