Documentation

API guide

Analyze images and videos by URL. Pass public media links, or upload via a signed URL then submit the returnedgs://object. Lens scores media in place and echoes the submitted URL in results.

Getting started

01
Get an API key
Open Console, sign in, create a key, and copy it. You’ll send this key on every API request.
02
Call the API with your key
Add headerX-Api-Key: YOUR_KEYon every request. Console login is only for managing keys — your backend uses the API key.
03
Submit URLs
POST /lens/caseswith JSON image/video URLs. For browser files, callPOST /lens/uploads/signfirst (GCS V4 PUT), then submit the durablegs://URL. Lens responds with a case id right away, then analyzes in the background.
04
Read the result
PollGET /lens/cases/{id}untilstatusiscompletedorfailed, then use the scores (or handle unsupported items).

Public or signed object URLs (CDN, S3, Lensgs:// from Upload / signed URL, etc.). Prefer a direct media link — engines may return unsupported for HTML share pages.

Credits: 1 per URL. Balance is in Console.

Examples

Replace YOUR_KEYwith a key from Console. Expand an example to see the full request.

1. Analyze an image URLJSON · remote URL

Pass a direct file URL. Same pattern works for gs://bucket/path.jpg. Response is a case id; poll it next.

curl -X POST https://api.lens.jdfive.com/lens/cases \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "images": [
        "https://my-bucket.s3.us-east-1.amazonaws.com/listings/shirt.jpg"
      ],
      "videos": []
    }
  }'

# Response
# { "id": "case_01hxyz…" }

2. Image + video togetherJSON · multiple items

One case can include several URLs. Cost is 1 credit per URL(here: 1 image + 1 video = 2 credits).

curl -X POST https://api.lens.jdfive.com/lens/cases \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "images": ["https://cdn.example.com/tee-front.jpg"],
      "videos": ["https://cdn.example.com/tee-spin.mp4"]
    }
  }'

3. Poll until scores are readyGET · after submit

Use the id from submit. Keep calling untilstatus is completedor failed. Each result echoes your url, may include a browser displayUrl, and may beunsupported if no engine could analyze it.

curl https://api.lens.jdfive.com/lens/cases/case_01hxyz \
  -H "X-Api-Key: YOUR_KEY"

{
  "id": "case_01hxyz",
  "status": "completed",
  "creditsCharged": 1,
  "createdAt": "2026-08-06T12:00:00Z",
  "completedAt": "2026-08-06T12:00:02Z",
  "results": [
    {
      "type": "image",
      "index": 0,
      "url": "https://cdn.example.com/shirt.jpg",
      "displayUrl": "https://cdn.example.com/shirt.jpg",
      "status": "completed",
      "scores": {
        "adult": { "label": "VERY_UNLIKELY", "score": 0.05, "rank": 1 },
        "racy": { "label": "UNLIKELY", "score": 0.25, "rank": 2 },
        "violence": { "label": "VERY_UNLIKELY", "score": 0.05, "rank": 1 }
      },
      "error": null
    }
  ]
}

label is the main signal for policy (VERY_UNLIKELY → VERY_LIKELY). Correlate items by url (or type + index).

Errors

Code	Meaning
401	Missing or invalid API key
402	Not enough credits
400	Empty body or blank URL
404	Case not found (or not yours)

Need help?Contact us· try a URL in the browser atTry Now.

API guide

Getting started

Get an API key

Call the API with your key

Submit URLs

Read the result

Examples

Errors