Analysis jobs - NanoClip API

Every analysis starts from an uploaded source. After upload completion, transcript, vision, and retake-removal commands are asynchronous: a start request returns quickly, and the result endpoint returns the current status plus any completed outputs. You can upload video or audio. Audio sources are transcript-only — vision and retake-removal return 422 Unprocessable Entity. Set content_type to the audio type you are uploading (e.g. audio/mpeg); see Allowed upload content types. For audio, the upload-complete response reports width and height as null and a source.media_kind of audio.

1. Upload source video or audio

Create an upload project:

curl -X POST "https://api.nanoclip.ai/v1/projects/upload" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "demo.mp4",
    "content_type": "video/mp4"
  }'

The response includes:

Field	Description
`project_id`	Project ID used for transcript and vision requests.
`source`	Customer-facing metadata for the uploaded source, such as filename, content type, `media_kind` (`video` or `audio`), and size when known.
`upload_url`	Signed URL that accepts the source bytes (video or audio).
`upload_headers`	Headers to include when uploading.
`upload_expires_in_seconds`	Time until the signed URL expires.

Upload the source bytes with the content_type you declared (the create response echoes it in upload_headers), then complete the upload:

# CONTENT_TYPE must match the content_type you declared above (e.g. video/mp4 or audio/mpeg)
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: $CONTENT_TYPE" \
  --data-binary "@demo.mp4"

curl -X POST "https://api.nanoclip.ai/v1/projects/proj_abc123/upload/complete" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY"

Analysis commands return 409 Conflict until upload completion succeeds. The completed upload response includes source metadata so you can confirm which source the project points to. For audio, width and height are null and source.media_kind is "audio". GET /v1/projects/{project_id} returns the same billing-basis fields — duration, source_size_bytes, width, height — so you can re-check them at any point in a project’s life without repeating the upload/complete call:

curl "https://api.nanoclip.ai/v1/projects/proj_abc123" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY"
# -> { "status": "ready", "duration": 612.3, "source_size_bytes": 48213099,
#      "width": 1920, "height": 1080, "source": { ... } }

All four are null until upload/complete has probed the source; width and height stay null for audio.

Audio example (transcript-only)

Upload an mp3 and transcribe it. Audio sources accept transcript only — vision and retake-removal return 422.

# 1. create the upload project with an audio content type
curl -X POST "https://api.nanoclip.ai/v1/projects/upload" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "episode.mp3", "content_type": "audio/mpeg" }'

# 2. PUT the bytes with the matching audio content type
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: audio/mpeg" \
  --data-binary "@episode.mp3"

# 3. complete — width/height come back null for audio
curl -X POST "https://api.nanoclip.ai/v1/projects/proj_abc123/upload/complete" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY"
# -> { "status": "ready", "duration": 612.3, "width": null, "height": null,
#      "source": { "media_kind": "audio", ... } }

Then start a transcript exactly as below (vision / retake-removal are not available for audio).

2. Transcript

Start transcript analysis after the project has a completed source upload.

curl -X POST "https://api.nanoclip.ai/v1/projects/proj_abc123/transcript" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en",
    "requested_outputs": ["text", "speakers", "utterances", "words"]
  }'

{
  "project_id": "proj_abc123",
  "analysis": "transcript",
  "status": "queued",
  "requested_outputs": ["text", "speakers", "utterances", "words"],
  "created_at": "2026-05-18T10:05:00Z"
}

Poll the transcript result endpoint:

curl "https://api.nanoclip.ai/v1/projects/proj_abc123/transcript" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY"

Completed transcript responses include agent context for timestamp units, speaker IDs, and word index ranges.

{
  "project_id": "proj_abc123",
  "analysis": "transcript",
  "status": "completed",
  "language": "en",
  "agent_context": {
    "time_unit": "seconds",
    "time_origin": "start of source video",
    "speaker_ids": "stable within this transcript response",
    "word_indices": "word_start_idx is inclusive; word_end_idx is exclusive"
  },
  "text": "Welcome to the demo...",
  "words": [
    {
      "text": "Welcome",
      "start": 0.0,
      "end": 0.42,
      "speaker": 0,
      "confidence": 0.98
    }
  ],
  "utterances": [
    {
      "speaker": 0,
      "start": 0.0,
      "end": 2.1,
      "text": "Welcome to the demo...",
      "word_start_idx": 0,
      "word_end_idx": 5
    }
  ],
  "speakers": [
    {"speaker": 0, "total_duration": 12.4, "utterance_count": 3}
  ]
}

Transcript language

language is required. Use one of the supported base tags. Supported base tags:

Value	Language
`bg`	Bulgarian
`cs`	Czech
`da`	Danish
`de`	German
`el`	Greek
`en`	English
`es`	Spanish
`et`	Estonian
`fi`	Finnish
`fr`	French
`he`	Hebrew
`hr`	Croatian
`hu`	Hungarian
`it`	Italian
`lt`	Lithuanian
`lv`	Latvian
`mt`	Maltese
`nl`	Dutch
`pl`	Polish
`pt`	Portuguese
`ro`	Romanian
`ru`	Russian
`sk`	Slovak
`sl`	Slovenian
`sv`	Swedish
`uk`	Ukrainian

Unsupported language tags return 422 Unprocessable Entity.

Speaker diarization

Pass diarize: true in the transcript request to run speaker diarization. It is optional and defaults to false.

{
  "language": "en",
  "requested_outputs": ["text", "speakers", "utterances", "words"],
  "diarize": true
}

Speaker data is only returned when diarize: true. With diarization off (the default), the speakers array is empty and the speaker field is omitted from words and utterances — you still get text, word timings, and utterance segmentation. Request diarize: true to receive per-word speaker labels and speaker summaries. Diarization is billed separately as an add-on to the transcript charge. See Credit billing for the current rate.

3. Vision

Start vision analysis with the outputs your app needs.

curl -X POST "https://api.nanoclip.ai/v1/projects/proj_abc123/vision" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_outputs": ["faces", "face_tracks", "scenes"]
  }'

Poll the vision result endpoint:

curl "https://api.nanoclip.ai/v1/projects/proj_abc123/vision" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY"

Completed vision responses include agent context, face observations over time, track summaries, scene timestamps, and an asd record describing whether active-speaker detection ran.

{
  "project_id": "proj_abc123",
  "analysis": "vision",
  "status": "completed",
  "error": null,
  "agent_context": {
    "coordinate_system": "normalized [x1, y1, x2, y2] in source video frame",
    "time_unit": "seconds",
    "scene_timestamp": "scene start time after t=0",
    "track_ids": "stable within this vision response"
  },
  "faces": [
    {
      "t": 0.0,
      "detections": [
        {
          "box": [0.2109, 0.2861, 0.2719, 0.4111],
          "score": 0.91,
          "track_id": 0,
          "cluster_id": 0
        }
      ]
    }
  ],
  "face_tracks": [
    {
      "track_id": 0,
      "cluster_id": 0,
      "frame_count": 13,
      "start_t": 0.0,
      "end_t": 2.4024,
      "median_box_area": 0.0067
    }
  ],
  "scenes": [
    {"timestamp": 2.6026}
  ],
  "asd": {
    "ran": true,
    "reason": null,
    "assigned": 12,
    "carried": 340
  }
}

Active-speaker detection (`asd`)

When active-speaker detection scores a face, that detection carries a speak_conf between 0 and 1. Detections that were never scored omit the field entirely — so without asd, “active-speaker detection never ran”, “it ran and scored nothing” and “it failed” all look identical in the response. The asd object tells them apart:

Field	Meaning
`ran`	Whether active-speaker detection executed for this job.
`reason`	Why it did not run, when `ran` is `false`.
`assigned`	How many tracks it scored.
`carried`	How many face detections carry a resulting `speak_conf`.

How to read it:

ran: true, carried > 0 — active-speaker confidences are present; use them.
ran: true, carried: 0 — it ran and scored nothing on this footage.
ran: false — it never ran, and reason says why.
asd absent (null) — the job predates this record. Absent is not the same answer as ran: false; do not treat them as equivalent.

Active-speaker detection needs at least two simultaneously tracked faces to compare. Footage with a single speaker on screen therefore produces no speak_conf, and that is expected rather than a failure — asd is how you tell the difference.

4. Retake removal

Retake removal requires a language, one of the same languages as transcript. It analyzes transcript-like word timing and returns the word spans to remove plus keep intervals for a clean read.

curl -X POST "https://api.nanoclip.ai/v1/projects/proj_abc123/retake-removal" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en"
  }'

{
  "project_id": "proj_abc123",
  "analysis": "retake_removal",
  "status": "queued",
  "created_at": "2026-06-08T10:05:00Z"
}

Poll the retake-removal result endpoint:

curl "https://api.nanoclip.ai/v1/projects/proj_abc123/retake-removal" \
  -H "Authorization: Bearer $NANOCLIP_API_KEY"

Completed responses include the original words, removal spans, and the keep intervals.

{
  "project_id": "proj_abc123",
  "status": "completed",
  "error": null,
  "words": [
    {
      "i": 0,
      "start": 0.0,
      "end": 0.42,
      "text": "Welcome",
      "confidence": 0.98,
      "source": "transcript"
    }
  ],
  "remove_spans": [
    {
      "remove_word_start": 12,
      "remove_word_end": 18
    }
  ],
  "keep_intervals": [
    {
      "start": 0.0,
      "end": 7.2
    }
  ]
}

Requested outputs

Analysis	Output	Description
Transcript	`text`	Combined transcript text.
Transcript	`words`	Word-level transcript entries with `text`, `start`, `end`, `speaker`, and optional `confidence`.
Transcript	`utterances`	Speaker turns with `speaker`, `start`, `end`, `text`, `word_start_idx`, and `word_end_idx`.
Transcript	`speakers`	Speaker summaries with `speaker`, `total_duration`, and `utterance_count`.
Vision	`faces`	Individual detected face observations.
Vision	`face_tracks`	Face observations grouped across time.
Vision	`scenes`	Scene-level visual segments.
Retake removal	`words`	Word-level inputs used by the retake-removal model.
Retake removal	`remove_spans`	Word index ranges that should be removed.
Retake removal	`keep_intervals`	Time ranges to keep after removing retakes.

The transcript and vision outputs above are the values accepted in each command’s requested_outputs. Retake removal has no requested_outputs selector and always returns words, remove_spans, and keep_intervals. agent_context and the vision response’s asd record are not selectable — they are always included in completed responses.

Polling pattern

Poll until status is completed or failed.

while true; do
  response=$(curl -s "https://api.nanoclip.ai/v1/projects/proj_abc123/transcript" \
    -H "Authorization: Bearer $NANOCLIP_API_KEY")

  echo "$response"
  status=$(echo "$response" | jq -r '.status')

  if [ "$status" = "completed" ] || [ "$status" = "failed" ]; then
    break
  fi

  sleep 5
done

If an analysis is already queued, processing, or completed, starting the same analysis again returns the existing analysis response.

​1. Upload source video or audio

​Audio example (transcript-only)

​2. Transcript

​Transcript language

​Speaker diarization

​3. Vision

​Active-speaker detection (asd)

​4. Retake removal

​Requested outputs

​Polling pattern

1. Upload source video or audio

Audio example (transcript-only)

2. Transcript

Transcript language

Speaker diarization

3. Vision

Active-speaker detection (`asd`)

4. Retake removal

Requested outputs

Polling pattern