Image Search

image-search (ZAI in-house, via z-ai SDK)

Searches public web images for a natural-language query, re-hosts each hit on OSS so the link is embeddable, and (optionally) attaches a short caption. The backend is ZAI's own self-developed image search service.

You do not call the backend directly, and you do not call the gateway HTTP API directly. Always go through the z-ai image-search subcommand from the z-ai-web-dev-sdk CLI — that's the only supported entry point.

When to activate

Trigger this skill when the user wants to:

• Find images for an article, slide deck, PPT, blog post, or report.
• Get reference photos / inspiration for a topic.
• Embed pictures into generated documents with stable URLs.
• Caption a set of images in Chinese or English.

Do not use this skill for:

• Generating new images from scratch — use z-ai image (image generation).
• Reverse image search ("what is this image of?").
• Searching images inside a private corpus — this hits public web sources.

Prerequisites

z-ai-web-dev-sdk installed, providing the z-ai binary:

npm install -g z-ai-web-dev-sdk
# or:  bun add -g z-ai-web-dev-sdk

Invocation

z-ai image-search --query "<natural-language sentence>" [flags]

The CLI prints the JSON response (pretty-formatted) to stdout, or writes it to --output <path> if supplied.

Flags

Examples

# Default search (5 images, cn region, captions on).
z-ai image-search -q "a cute orange tabby kitten playing with yarn" --count 5

# US region, no captioning (faster).
z-ai image-search -q "vintage red sports car on a mountain road" --count 5 --gl us --no-rank

# Chinese query — captions come back in Chinese.
z-ai image-search -q "中国传统水墨山水画" --count 5 -o results.json

Choosing parameters

• --query: use a descriptive sentence, not a keyword list. The service is tuned for natural language and returns more on-topic results that way. Match the language to the audience: Chinese queries produce Chinese captions, English queries produce English captions.
• --count: default to 5 for most asset-gathering tasks. Drop to 1–3 when the user only needs one finalist; raise toward 10–20 when building a moodboard or browsing options. Stay within 1–20.
• --no-rank: turn captions off for moodboards or when latency matters; leave them on when the user will pick images by reading the captions.
• One concept per call: for two unrelated subjects, fire two separate invocations rather than concatenating keywords.

Response shape

{
  "success": true,
  "query": "cute orange tabby kitten",
  "count": 5,
  "ranked": true,
  "results": [
    {
      "original_url": "https://sfile.chatglm.cn/images-ppt/<hash>.png",
      "caption": "A cute orange tabby kitten playing with yarn on a rug.",
      "source": "Unsplash",
      "original_width": "750px",
      "original_height": "500px"
    }
  ]
}

Failure response (HTTP is still 200; check success):

{
  "success": false,
  "query": "...",
  "count": 0,
  "ranked": true,
  "results": [],
  "error": "<human-readable reason>"
}

Field reference

Operating tips

1. Always present the OSS original_url, not the source site URL. The OSS link is the one that's guaranteed reachable; source pages may be paywalled, geo-blocked, or deleted.
2. Skip captioning for speed. --no-rank typically cuts response time by more than half. Use it when you'll caption results yourself.
3. Be patient with timeouts. A full call can take 90 seconds or more — the upstream does image reachability probes, OSS upload, and captioning one after another. Use a client-side timeout of at least 120 seconds.
4. Region matters. gl=cn biases toward Chinese-language sources; gl=us toward English. Pick the one that matches the user's audience.

Error handling