Image Search API

The Image Search API returns images for a query, with the page that shows each image. Use it to implement an image search tool for any model or agent framework. The model calls your tool, your backend calls this endpoint, and the results go back to the model.

Endpoint: POST https://api.thesys.dev/v1/search/images

The endpoint is not OpenAI compatible, so call it with fetch or another HTTP client. Server calls use the API key described in Authentication.

Make a request

export async function searchImages(query: string) {
  const response = await fetch("https://api.thesys.dev/v1/search/images", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.THESYS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query, num_results: 5 }),
  });

  if (!response.ok) {
    throw new Error(`Image search failed: ${response.status}`);
  }

  return response.json();
}

Request

Read the result

results holds the matches, and can hold fewer than num_results. usage.search_units reports the searches charged, and is always 1.

A search with one result:

{
  "query": "golden gate bridge at night",
  "results": [
    {
      "title": "Golden Gate Bridge at night",
      "image_url": "https://images.example.com/ggb-night.jpg",
      "page_url": "https://example.com/san-francisco-at-night",
      "source": "example.com",
      "width": 1200,
      "height": 800,
      "thumbnail_url": "https://thumbs.example.com/ggb-night.jpg",
      "mime_type": "image/jpeg"
    }
  ],
  "usage": { "search_units": 1 }
}

Use as a function tool

Declare the tool in your model request. This example uses the Chat Completions format. When the model calls the tool, call searchImages in your backend and return the results as the tool result. The loop is the same as for any other function tool. See Function tools.

export const searchImagesTool = {
  type: "function",
  function: {
    name: "search_images",
    description: "Find images on the web.",
    parameters: {
      type: "object",
      properties: { query: { type: "string", description: "What to search for" } },
      required: ["query"],
    },
  },
} as const;

The Responses API can also run image search inside the Gateway, with no function tool. See Hosted Tools.

Data

The query you send is passed to a third-party search provider. The query and the results are not stored beyond the request logs.

Pricing

Each successful call is charged a flat price from your credits, and does not use a plan API call. A call that finds no results is still charged. A failed call is free. See Pricing for the current rate.

Errors

The endpoint returns the same error shape as the Chat Completions and Responses APIs. For a 400, message is a list of every problem.