Text to Image by Person Search

POST

https://api.coactive.ai/api/v1/search/text-to-image/by-person

POST

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

$ curl -X POST https://api.coactive.ai/api/v1/search/text-to-image/by-person \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "dataset_id": "c40276f0-024b-4a3f-b3e6-dcf0d304843e",
>   "text_query": "Jane Doe speaking at the 2023 Climate Summit",
>   "asset_type": "keyframe"
> }'

1 {
2   "data": [
3     {
4       "coactive_image_id": "a3f1c9e2-7b4d-4f8a-9c2e-5d6f7a8b9c0d",
5       "asset_type": "keyframe",
6       "dataset_id": "c40276f0-024b-4a3f-b3e6-dcf0d304843e",
7       "video_id": "d9f8e7c6-b5a4-4d3f-8e2b-1c0a9f8e7d6c",
8       "composite_slice_id": "e1f2d3c4-b5a6-7d8e-9f0a-b1c2d3e4f5a6",
9       "composite_type": "shot",
10       "composite_start_time_ms": 452300,
11       "composite_end_time_ms": 457800,
12       "moderation_score": 0.03
13     }
14   ],
15   "videos": [
16     {
17       "video_id": "d9f8e7c6-b5a4-4d3f-8e2b-1c0a9f8e7d6c",
18       "moderation_score": 0.05
19     }
20   ]
21 }

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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

dataset_idstringRequiredformat: "uuid"

The unique identifier for the dataset

text_querystringRequired

The text query to search for

asset_typeenumRequired

Visual asset type to search over. For datasets using the native video data model, only 'keyframe' is supported.

offsetintegerOptional0-9223372036854776000Defaults to 0

Starting index to return

limitintegerOptional1-1000Defaults to 100

Max number of items to return

metadata_filtersobject or nullOptional

List of metadata filters to apply to the search

moderation_score_typeenumOptional

Type of moderation scores to return when moderation is enabled.probability returns scores 0-1 using BGE Reranker model.level returns scores 0-5 using OpenAI model.This does not enable/disable moderation - use skip_moderation for that.

negative_textstring or nullOptional

Optional text describing what to exclude from search results. Steers the query embedding away from this direction.

person_idslist of strings or nullOptional

List of person IDs to filter results by. Currently only a single person_id is supported.

person_names_or_aliaseslist of strings or nullOptional

List of person names/aliases to filter results by. Currently only a single person name is supported.

skip_moderationbooleanOptionalDefaults to false

Skip content moderation if enabled

Response

Successful Response

datalist of objects

The search results matching the person filter

videoslist of objects

Search results aggregated by video, ordered by best matching keyframe score

Errors

422

Unprocessable Entity Error