---
title: "Image to Image Search"
method: POST
path: "/api/v1/search/image-to-image"
tags: ["search > search"]
---

# Image to Image Search

`POST /api/v1/search/image-to-image`

Find visually similar images using a reference image. Provide the reference as either a coactive_image_id (an asset already in the dataset) or a public_url.Useful for finding visually related assets.

## Headers

- `Authorization` string, required

## Request body

- SearchImageSearchRequest — Image search request. Either CID or public_url must be provided.
  - `dataset_id` string, uuid, required — The unique identifier for the dataset
  - `offset` integer — Starting index to return
  - `limit` integer — Max number of items to return
  - `metadata_filters` SearchMetadataFilters
    - `filters` SearchMetadataFiltersFiltersItems[], required
      - union
        - SearchBooleanEqualsClause
          - `key` string, required
          - `operator` '==', required
          - `value` boolean, required
        - SearchEqualsClause
          - `key` string, required
          - `operator` '==', required
          - `value` string, required
        - SearchNotEqualsClause
          - `key` string, required
          - `operator` '!=', required
          - `value` string, required
        - SearchDateTimeRangeInclusiveClause
          - `key` string, required
          - `start_utc_epoch` number, double, nullable
          - `end_utc_epoch` number, double, nullable
          - `operator` 'DateTimeRangeInclusive', required
  - `moderation_score_type` 'probability' | 'level' — Score type returned by the moderation service. - PROBABILITY: Scores in range 0-1 (uses BGE Reranker model) - LEVEL: Scores in range 0-5 (uses OpenAI model)
  - `coactive_image_id` string, uuid, nullable — The image to search for represented with a CID
  - `public_url` string, nullable — The image to search for represented with a public http url
  - `upload_id` string, nullable — The upload ID to search for
  - `asset_type` 'image' | 'video'
  - `skip_moderation` boolean — Skip content moderation if enabled

## Response `200`

Successful Response

- SearchAppApiRoutesSearchV1SchemaSchemaSearchResponse — Base search response
  - `data` SearchAppApiRoutesSearchV1SchemaSchemaSearchResponseDataItems[], required — The paginated results
    - union
      - SearchImage — An image asset response
        - `created_user_id` string, required — The user that created the resource
        - `created_dt` string, date-time, required — The created datetime of the resource
        - `updated_user_id` string, required — The user that last updated the resource
        - `updated_dt` string, date-time, required — The datetime the resource was last updated
        - `coactive_image_id` string, uuid, required — The coactive image id
        - `path` string, nullable — The original path of the image
        - `metadata` object, nullable — The user provided metadata for the image
        - `moderation_score` number, double, nullable — The moderation score of the image
      - SearchAppApiRoutesSearchV1SchemaSchemaKeyframe — A keyframe asset response
        - `coactive_image_id` string, uuid, required — The coactive image id
        - `video` SearchVideo, required — A video asset response
          - `created_user_id` string, required — The user that created the resource
          - `created_dt` string, date-time, required — The created datetime of the resource
          - `updated_user_id` string, required — The user that last updated the resource
          - `updated_dt` string, date-time, required — The datetime the resource was last updated
          - `path` string, nullable — The original path of the video
          - `coactive_video_id` string, uuid, required — The coactive video id
          - `metadata` object, nullable — The user provided metadata for the video
        - `shot` SearchShot, required — Metadata about a video shot
          - `shot_id` string, uuid, required — The unique shot id
          - `start_time_ms` integer, required — The start time in milliseconds from the beginning of the video
          - `end_time_ms` integer, required — The end time in milliseconds from the beginning of the video
        - `audio_segment` SearchAudioSegment — Metadata about a video audio segment
          - `start_time_ms` integer, required — The start time in milliseconds of the beginning of the audio clip
          - `end_time_ms` integer, required — The end time in milliseconds of the end of the audio clip
          - `speech_to_text_transcription` string, required — The text transcription of the audio clip
        - `timestamp` integer, nullable — The timestamp of the keyframe in the video in milliseconds
        - `moderation_score` number, double, nullable — The moderation score of the image
        - `keyframe_is_v1` boolean — Whether the keyframe is from the v1 video data model

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/coactive/apis/api-reference.md) · [All operations](https://skmtc.dev/coactive/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/coactive/api-reference/revisions/1223758be9ba/schema)