Deploy preview
In progress
meta:
usage:
num_search_queries: 1
latency: 1342
'400':
description: >-
Missing parameter inputs — Returned when a required parameter is
missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 400
msg: Missing parameter inputs
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/InsufficientBalance'
'413':
$ref: '#/components/responses/PayloadTooLarge'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'422':
description: >-
Input unreadable or invalid — Returned when an input cannot be read
or is otherwise invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 422
msg: Input unreadable or invalid
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
ImageSearchRequest:
type: object
required:
- inputs
description: Request body for the Image Search API.
properties:
inputs:
type: array
maxItems: 2
description: >-
Multimodal input array carrying text and/or image input (at most 1
text and 1 image).
items:
$ref: '#/components/schemas/ImageSearchInput'
topic:
type: string
enum:
- general
- design
default: general
description: >-
Industry scenario. Use `general` for general image search, or
`design` for design-asset search.
count:
type: integer
minimum: 1
maximum: 10
default: 5
description: Number of results to return.
include_domains:
type: array
items:
type: string
description: Domains to include, matched against each result's `source_page` URL.
exclude_domains:
type: array
items:
type: string
description: Domains to exclude, matched against each result's `source_page` URL.
time_range:
type: string
enum:
- day
- week
- month
- year
- d
- w
- m
- 'y'
description: >-
Relative time window counting back from the current time, filtered
by publish time. Mutually exclusive with `start_time`/`end_time` —
if both are provided, `start_time`/`end_time` take precedence.
start_time:
type: string
format: date-time
description: Start time for filtering results by publish time. ISO 8601 format.
example: '2025-01-01T00:00:00+08:00'
end_time:
type: string
format: date-time
description: End time for filtering results by publish time. ISO 8601 format.
example: '2025-01-01T00:00:00+08:00'
safesearch:
type: string
enum:
- 'off'
- strict
default: strict
description: >-
Controls filtering of explicit/adult content. `off` disables
filtering; `strict` drops all adult content.
html_snippet:
allOf:
- $ref: '#/components/schemas/HtmlSnippetOptions'
description: >-
Only effective when `topic=design`; controls whether an
`html_snippet` is returned for each result.
ImageSearchResponse:
type: object
description: A successful Image Search response.
properties:
request_id:
type: string
description: The unique identifier for this request.
data:
$ref: '#/components/schemas/ImageSearchData'
meta:
$ref: '#/components/schemas/ImageSearchMeta'
ErrorResponse:
type: object
properties:
code:
type: integer
description: Business status code. Non-zero values indicate an error.
msg:
type: string
description: A human-readable message describing the error.
required:
- code
- msg
ImageSearchInput:
type: object
required:
- type
description: >-
A single multimodal input. At most one text and one image input per
request.
properties:
type:
type: string
enum:
- text
- image
description: >-
The input type. A single image must be at most 5MB and one of: JPEG,
PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, SGI.
url:
type: string
description: >-
Image input as a public URL. For an image input, provide either
`url` or `data`, not both.
data:
type: string
description: >-
When `type` is `text`: the query content, max 500 characters. When
`type` is `image`: base64-encoded image data, at most 5MB after
encoding.
HtmlSnippetOptions:
type: object
description: >-
Only effective when `topic=design`; controls whether an `html_snippet`
is returned for each result.
properties:
enable:
type: boolean
default: false
description: If `true`, returns an `html_snippet` for each image result.
max_tokens:
type: integer
default: 5000
minimum: 100
maximum: 100000
description: Maximum tokens of `html_snippet` returned per image result.
ImageSearchData:
type: object
description: The main response payload.
properties:
results:
type: array
description: A list of image search results.
items:
$ref: '#/components/schemas/ImageSearchResult'
ImageSearchMeta:
type: object
description: Additional metadata for the Image Search request.
properties:
usage:
$ref: '#/components/schemas/ImageSearchUsage'
latency:
type: number
description: Response time in milliseconds.
warning:
type: string
nullable: true
description: Warning message, if any.
ImageSearchResult:
type: object
description: A single image search result.
properties:
title:
type: string
description: The title of the image.
url:
type: string
description: The image URL.
source_page:
type: string
description: URL of the original page hosting the image.
description:
type: string
description: Server-generated text description of the image content.
width:
type: integer
description: Image width in pixels.
height:
type: integer
description: Image height in pixels.
thumbnail:
type: string
description: Thumbnail URL.
time_published:
type: string
format: date-time
description: Publish time in ISO 8601.
time_last_crawled:
type: string
format: date-time
description: Last crawl time in ISO 8601.
summary:
type: string
description: >-
Structured description of the design asset, covering category,
layout, style, tags, and more. Returned only when `topic=design`.
html_snippet:
type: string
description: >-
HTML/CSS snippet that an LLM can reuse directly. Returned only when
`topic=design` and `html_snippet.enable` is `true`.
ImageSearchUsage:
type: object
description: Usage information for the Image Search request.
properties:
num_search_queries:
type: integer
description: Number of search queries executed.
responses:
Unauthorized:
description: Invalid API Key — Returned when the API key is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 401
msg: Invalid API Key
InsufficientBalance:
description: >-
Insufficient balance in account — Returned when the account balance is
insufficient to complete the request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 403
msg: Insufficient balance in account
PayloadTooLarge:
description: >-
Payload too large — Returned when the request payload exceeds the size
limit.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 413
msg: Payload too large
UnsupportedMediaType:
description: >-
Unsupported media type — Returned when the input media format is not
supported.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 415
msg: Unsupported media type
RateLimited:
description: >-
Exceeding the rate limit — Returned when the request exceeds the
configured rate limit.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 429
msg: Exceeding the rate limit
InternalError:
description: Internal error — Returned when an unexpected server-side error occurs.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: 500
msg: Internal error
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
API key used for request authentication. Obtain an API key before using
the API. Note: A payment method is required to use the API.
````