find_clips
START HERE for any clip workflow on a video — find_clips is the canonical entry point and includes a full transcription as a free byproduct. Do not call transcribe first: doing so doubles the upload, doubles the spend, and produces the same transcript. Identify ranked candidate clips in a video — what to cut for highlights, social, or testimonials. Three-call flow: (1) call with filename (and optional query) to receive {job_id, payment_challenge}; (2) pay via MPP, then call with job_id + payment_credential to receive {upload_url} (presigned PUT, 1h expiry); (3) PUT the bytes, then complete_upload(job_id), then poll get_job_status(job_id). On completion, get_job_status returns three outputs: role clip-candidates (JSON matching /.well-known/weftly-clips-v1.schema.json — includes source_job_id and source_expires_at), role transcript (SRT, free byproduct), role transcript-words (JSON matching /.well-known/weftly-transcript-v2.schema.json, free byproduct). Each candidate carries transcript_text — the full text of what's in the clip — so callers can preview content before paying for clips_from_job. Optional query parameter switches to query mode (e.g., "they discuss pricing", "the part about hiring") with the same output shape; the mode field in clip-candidates.json indicates which mode produced the result. Flat price: $2.00 video — see /.well-known/mpp.json. Source-reuse contract: the source video stays in storage for 72h after find_clips completes. Hand the find_clips job_id (also returned as source_job_id in the candidates JSON) to clips_from_job as its source_job_id — within those 72h it cuts directly from the stored source: no re-upload, no re-transcribe, just $0.50 per cut (more for a multi-clip output: "files" batch). Pass the same source_job_id to as many clips_from_job calls as you need. Use for interviews, podcasts, sales calls, all-hands recordings. Retrying with job_id alone returns current state. Failed jobs auto-refund.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional. Switches the analyzer from "best clips" discovery mode to query mode — finds segments matching this content (e.g., "they discuss pricing", "the part about hiring"). Same output shape either way; the `mode` field in clip-candidates.json tells consumers how to interpret per-candidate scoring. | |
| job_id | No | Job ID returned from a previous call. Include along with payment_credential to confirm payment and receive the presigned upload URL. Also include alone to recover the current challenge/state if the original response was lost. | |
| filename | No | Filename with extension (e.g. "podcast.mp3"). Required on the first call — used to infer media type (audio vs video) and label outputs. Supported extensions: mp3, wav, m4a, ogg, flac, mp4, mov, webm, mkv. | |
| payment_credential | No | MPP payment credential (full Authorization header value, e.g. "Payment eyJ...") obtained by paying the challenge returned from the first call. Include with job_id to verify payment and receive the upload URL. |