Skip to main content

​
Search

Three endpoints:
  • POST /v1/search — text or image query
  • POST /v1/search/similar — find clips similar to a reference
  • POST /v1/embeddings/query — raw embedding similarity

​
Text search

results = client.search("someone soldering a circuit board")
for match in results.items:
    print(match.clip_id, match.similarity_score, match.match_summary)
    print(match.preview_image_url)
Pass a base64-encoded image. URL-based image queries are restricted to allowlisted hosts — use base64 if your URL gets rejected. 
import base64

with open("photo.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

results = client.search.query(query_image_base64=b64, page_size=10)

​
Find similar

Given a clip, frame, or image — find the most similar content. 
# By clip
similar = client.search.similar(reference_clip_id="CLIP_ID")

# By frame
similar = client.search.similar(reference_frame_id="FRAME_ID")

# By image
similar = client.search.similar(reference_image_base64=b64)

​
Filters

All search endpoints accept:
ParameterTypeWhat it does
factory_idsstring[]Only these factories
worker_idsstring[]Only these workers
exclude_factory_idsstring[]Skip these factories
exclude_worker_idsstring[]Skip these workers
collection_idstringSearch within a collection
created_afterstringISO date lower bound
created_beforestringISO date upper bound
results = client.search.query(
    query_text="assembly line",
    factory_ids=["factory-1", "factory-2"],
    created_after="2025-01-01",
    page_size=20,
)

​
Pagination

All search results use cursor pagination: 
{
  "items": [...],
  "pagination": {
    "cursor": "abc123",
    "has_more": true,
    "page_size": 10
  }
}
Pass cursor from the previous response to get the next page. Stop when has_more is false.