Google Cloud Vision API × Antigravity で画像分析アプリを作る実践ガイド

# .rules（プロジェクトルート）
You are working on a Python project using Google Cloud Vision API.
- Always use google-cloud-vision >= 3.7 package
- Store API credentials in .env file, never hardcode
- Use GOOGLE_APPLICATION_CREDENTIALS for service account auth
- Error handling is required for all API calls
- Use Python 3.11+

# ❌ やってはいけない（パスがコードに露出する）
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/Users/masaki/keys/service-account.json"

# .env（.gitignore に必ず追加する）
GOOGLE_APPLICATION_CREDENTIALS=./credentials/service-account.json
GOOGLE_CLOUD_PROJECT=your-project-id

# アプリ側
from dotenv import load_dotenv
load_dotenv()
 
# GOOGLE_APPLICATION_CREDENTIALS は google-cloud ライブラリが自動で読み込む

# vision_client.py
import os
from google.cloud import vision
from dotenv import load_dotenv
 
load_dotenv()
 
def analyze_image_labels(image_path: str) -> list[dict]:
    """
    画像ファイルを分析してラベルのリストを返す
 
    Returns:
        list[dict]: [{"description": "Dog", "score": 0.98}, ...]
 
    Raises:
        RuntimeError: Vision API がエラーレスポンスを返した場合
        FileNotFoundError: 指定ファイルが存在しない場合
    """
    client = vision.ImageAnnotatorClient()
 
    with open(image_path, "rb") as f:
        content = f.read()
        image = vision.Image(content=content)
 
    response = client.label_detection(image=image)
 
    # ステータスが 200 でもレスポンス内にエラーが含まれることがある
    if response.error.message:
        raise RuntimeError(
            f"Vision API エラー: {response.error.message}\n"
            "詳細: https://cloud.google.com/apis/design/errors"
        )
 
    return [
        {
            "description": label.description,
            "score": round(label.score, 4),
            "topicality": round(label.topicality, 4),
        }
        for label in response.label_annotations
    ]
 
if __name__ == "__main__":
    labels = analyze_image_labels("sample.jpg")
    for label in labels:
        print(f"{label['description']}: {label['score']:.1%}")
 
    # 出力例:
    # Dog: 98.6%
    # Puppy: 95.2%
    # Carnivore: 93.8%

def analyze_image_from_url(image_url: str) -> list[dict]:
    """
    画像 URL を指定してラベル分析を行う
 
    Note:
        パブリックアクセス可能な URL のみ動作。
        認証が必要な URL や内部 URL は使用不可。
 
    Raises:
        RuntimeError: Vision API エラー時
    """
    client = vision.ImageAnnotatorClient()
 
    image = vision.Image()
    image.source.image_uri = image_url
 
    response = client.label_detection(image=image)
 
    if response.error.message:
        raise RuntimeError(f"Vision API エラー: {response.error.message}")
 
    return [
        {"description": label.description, "score": round(label.score, 4)}
        for label in response.label_annotations
    ]

# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, HttpUrl
from vision_client import analyze_image_from_url
 
app = FastAPI(title="Vision API Service")
 
class ImageAnalysisRequest(BaseModel):
    url: HttpUrl
 
class LabelResult(BaseModel):
    description: str
    score: float
 
@app.post("/analyze", response_model=list[LabelResult])
async def analyze_image(request: ImageAnalysisRequest):
    """画像 URL を受け取ってラベルのリストを返す"""
    try:
        labels = analyze_image_from_url(str(request.url))
        return labels
    except RuntimeError as e:
        # Vision API 側のエラーは 502 で返す
        raise HTTPException(status_code=502, detail=f"Vision API エラー: {e}")
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"内部エラー: {e}")
 
@app.get("/health")
async def health_check():
    return {"status": "ok"}

# Antigravity のターミナルで確認
echo $GOOGLE_APPLICATION_CREDENTIALS
python -c "from google.auth import default; creds, project = default(); print(f'Project: {project}')"

# 開発時の簡易レート制限
import time
 
_request_count = 0
_MAX_DEV_REQUESTS = 50
 
def analyze_with_limit(image_url: str) -> list[dict]:
    global _request_count
    if _request_count >= _MAX_DEV_REQUESTS:
        raise RuntimeError("開発用リクエスト上限に達しました")
    _request_count += 1
    time.sleep(0.1)  # 連続リクエストを少し抑制
    return analyze_image_from_url(image_url)