---
title: "Text to Image by Person Search"
method: POST
path: "/api/v1/search/text-to-image/by-person"
tags: ["search > search"]
---

# Text to Image by Person Search

`POST /api/v1/search/text-to-image/by-person`

Search for video keyframes that match a text query and contain a specific enrolled person — for example, Jane Doe at a press conference. Specify the person via either person_ids or person_names_or_aliases.The person must already be enrolled in your organization. Returns matching assets plus a video-level list aggregated by best matching keyframe score.

## Headers

- `Authorization` string, required

## Request body

- SearchTextSearchByPersonRequest — Text search filtered by person request
  - `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)
  - `text_query` string, required — The text query to search for
  - `negative_text` string, nullable — Optional text describing what to exclude from search results. Steers the query embedding away from this direction.
  - `person_ids` string[], nullable — List of person IDs to filter results by. Currently only a single person_id is supported.
  - `person_names_or_aliases` string[], nullable — List of person names/aliases to filter results by. Currently only a single person name is supported.
  - `asset_type` 'image' | 'keyframe', required
  - `skip_moderation` boolean — Skip content moderation if enabled

## Response `200`

Successful Response

- SearchTextSearchByPersonResponse — Response for person-filtered text-to-image search
  - `data` SearchImageResult[], required — The search results matching the person filter
    - `coactive_image_id` string, uuid, required — The unique identifier of the image/keyframe
    - `asset_type` 'image' | 'keyframe', required
    - `dataset_id` string, uuid, required — The dataset identifier this asset belongs to
    - `video_id` string, uuid, nullable — The video identifier (for video keyframes only)
    - `composite_slice_id` string, uuid, nullable — The composite slice identifier (for video keyframes only)
    - `composite_type` 'shot' | 'scene' | 'segment' — Type of composite for video keyframes
    - `composite_start_time_ms` integer, nullable — The start time of the composite slice in milliseconds (for video keyframes only)
    - `composite_end_time_ms` integer, nullable — The end time of the composite slice in milliseconds (for video keyframes only)
    - `moderation_score` number, double, nullable — The moderation score of the asset (if applicable)
  - `videos` SearchTextSearchByPersonVideoResult[] — Search results aggregated by video, ordered by best matching keyframe score
    - `video_id` string, uuid, required — The unique identifier of the video
    - `moderation_score` number, double, nullable — The moderation score of the video

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-22** `1223758be9ba` — 4 warning
  - the `limit` request property's max was set to `1000.00`
  - the `offset` request property's max was set to `9223372036854775808.00`
  - the `limit` request property's min was set to `1.00`
  - the `offset` request property's min was set to `0.00`

[Change history](https://skmtc.dev/coactive/apis/api-reference/changes/api/v1/search/text-to-image/by-person/post.md)

---

[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)