> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenkit.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Web Search

> Finds the best web image match from a semantic query

## Request body

`application/json` (or form body, depending on your client setup)

* `instructions` (`string`, required): Between `3` and `10,000` characters
* `aspect_ratio` (`"any" | validAspectRatios`, optional): Defaults to `"any"`
* `effort` (`"high" | "low"`, optional): Defaults to `"low"`

## Validation rules

* `instructions` minimum length: `3`
* `instructions` maximum length: `10,000`


## OpenAPI

````yaml POST /v2/image-utils/image-web-search
openapi: 3.1.0
info:
  title: TokenKit
  description: >-
    Building image agents and tools, with APIs for businesses that want to put
    them to work.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tokenkit.co
security:
  - bearerAuth: []
paths:
  /v2/image-utils/image-web-search:
    post:
      description: Generate image instructions with optional web search guidance.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImageWebSearchRequest'
      responses:
        '202':
          description: Job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '400':
          description: Validation error
        '429':
          description: Queue saturated
components:
  schemas:
    ImageWebSearchRequest:
      type: object
      properties:
        instructions:
          type: string
          minLength: 3
          maxLength: 10000
        aspect_ratio:
          $ref: '#/components/schemas/ImageAspectRatioOrAny'
        effort:
          allOf:
            - $ref: '#/components/schemas/ImageEffort'
          default: low
      required:
        - instructions
    JobAccepted:
      type: object
      properties:
        data:
          type: object
          properties:
            job_id:
              type: string
              example: job_123
            links:
              $ref: '#/components/schemas/JobLinks'
          required:
            - job_id
            - links
        errors:
          nullable: true
      required:
        - data
    ImageAspectRatioOrAny:
      type: string
      enum:
        - any
        - '9:16'
        - '2:3'
        - '3:4'
        - '4:5'
        - '1:1'
        - '5:4'
        - '4:3'
        - '3:2'
        - '16:9'
      default: any
    ImageEffort:
      type: string
      enum:
        - high
        - low
    JobLinks:
      type: object
      properties:
        self:
          type: string
          example: /v1/jobs/job_123
        stream:
          type: string
          example: /v1/jobs/job_123/stream
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````