---
title: "Find a moment from a natural-language query (creates a clip)"
method: POST
path: "/api/videos/{id}/search"
tags: ["smart"]
---

# Find a moment from a natural-language query (creates a clip)

`POST /api/videos/{id}/search`

## Request

- Base URL: `https://cliponit.app`
- URL: `https://cliponit.app/api/videos/{id}/search`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `session`
  - OAuth 2 (authorization code, authorization URL `https://cliponit.app/oauth/authorize`, token URL `https://cliponit.app/oauth/token`, scopes: `clips`)

AI search over the transcript; creates a new clip appended to the list and returns it. Requires a transcript (video `ready`). Free plan: 5 searches/day → 402 beyond.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `query` string, required

## Response `200`

New clip

- Clip
  - `id` string, uuid, required
  - `video_id` string, uuid, required
  - `position` integer, required: Chronological order
  - `title` string, required
  - `start_s` number, required: Absolute start in the source video (seconds)
  - `end_s` number, required: Absolute end (seconds)
  - `created_at` string, required
  - `score` integer, nullable: Estimated viral potential (AI)
  - `reason` string, nullable: One sentence explaining the score, in the transcript language
  - `description` string, nullable: Ready-to-post caption (null until `describeClip`)
  - `hashtags` string[], nullable: Without `#`
  - `thumbnail_url` string, nullable: `/files/thumbs/clips/<clip_id>.jpg`, 320 px frame at start_s + 1

## Other responses

- `400`: Validation error — the message names the field, e.g. `champ subtitles.size invalide : attendu 1..3`
- `402`: Plan quota reached (monthly videos, daily searches, file size/duration on free)

---

[API](https://skmtc.dev/cliponit/apis/cliponit-api.md) · [All operations](https://skmtc.dev/cliponit/apis/cliponit-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cliponit/apis/cliponit-api/revisions/10e3e4327922?raw)