> ## Documentation Index
> Fetch the complete documentation index at: https://reel25.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Analysis

> Start AI-powered video analysis

Triggers an AI analysis for a video. The analysis runs asynchronously in the background and typically takes **15–30 seconds** to complete.

<Info>
  Each analysis costs **5 credits**. Credits are deducted only after successful completion — failed analyses are not charged.
</Info>

## Path parameters

<ParamField path="videoId" type="string" required>
  The video UUID to analyze.
</ParamField>

## Query parameters

<ParamField query="force" type="boolean" default="false">
  Force re-analysis even if a completed analysis already exists. Deletes the previous result and starts fresh.
</ParamField>

## Polling for results

After triggering, poll `GET /video-analysis/{videoId}` every 5-10 seconds until `status` is `completed` or `failed`. Average analysis time is **15–30 seconds**.

The `transcribed` status indicates partial results are available — the transcript and segments are ready while visual analysis continues.

```
pending → downloading → transcribed → analyzing → completed
                                                 ↘ failed
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    -H "Authorization: Bearer reel25_sk_..." \
    https://api.reel25.com/api/v1/video-analysis/550e8400-e29b-41d4-a716-446655440000/analyze
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.reel25.com/api/v1/video-analysis/550e8400-e29b-41d4-a716-446655440000/analyze',
    {
      method: 'POST',
      headers: { 'Authorization': 'Bearer reel25_sk_...' }
    }
  );
  const { data } = await response.json();
  // data.status === 'pending' — start polling GET endpoint
  ```

  ```python Python theme={null}
  import requests
  import time

  video_id = '550e8400-e29b-41d4-a716-446655440000'
  headers = {'Authorization': 'Bearer reel25_sk_...'}

  # Trigger analysis
  response = requests.post(
      f'https://api.reel25.com/api/v1/video-analysis/{video_id}/analyze',
      headers=headers
  )
  print(response.json())  # {"data": {"status": "pending", ...}}

  # Poll for results
  while True:
      result = requests.get(
          f'https://api.reel25.com/api/v1/video-analysis/{video_id}',
          headers=headers
      ).json()

      status = result['data']['status'] if result['data'] else None
      if status in ('completed', 'failed', None):
          break
      time.sleep(10)

  print(result['data'])
  ```
</RequestExample>

<ResponseExample>
  ```json 202 — queued theme={null}
  {
    "data": {
      "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "videoId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending"
    },
    "message": "Video analysis queued"
  }
  ```

  ```json 202 — already completed theme={null}
  {
    "data": {
      "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "videoId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed"
    },
    "message": "Analysis already completed"
  }
  ```

  ```json 202 — in progress theme={null}
  {
    "data": {
      "analysisId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "videoId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "analyzing"
    },
    "message": "Analysis in progress"
  }
  ```

  ```json 400 — insufficient credits theme={null}
  {
    "statusCode": 400,
    "message": "Not enough credits. Video analysis costs 5 credits, you have 2."
  }
  ```

  ```json 404 — video not found theme={null}
  {
    "code": "NOT_FOUND",
    "message": "Video not found"
  }
  ```
</ResponseExample>

## Full example: analyze and wait

```javascript Node.js theme={null}
async function analyzeVideo(videoId, apiKey) {
  const base = 'https://api.reel25.com/api/v1';
  const headers = { 'Authorization': `Bearer ${apiKey}` };

  // 1. Trigger analysis
  await fetch(`${base}/video-analysis/${videoId}/analyze`, {
    method: 'POST', headers
  });

  // 2. Poll until done
  while (true) {
    const res = await fetch(`${base}/video-analysis/${videoId}`, { headers });
    const { data } = await res.json();

    if (!data || data.status === 'failed') {
      console.error('Analysis failed:', data?.error);
      return null;
    }

    if (data.status === 'completed') {
      return data;
    }

    // Show partial results when transcribed
    if (data.status === 'transcribed') {
      console.log('Transcript ready:', data.transcript?.slice(0, 100));
    }

    await new Promise(r => setTimeout(r, 10000));
  }
}

const analysis = await analyzeVideo('550e8400-...', 'reel25_sk_...');
console.log('Hook:', analysis.hookStyle, '-', analysis.hookPhrase);
console.log('UGC:', analysis.ugcFit, `(${analysis.ugcConfidence}%)`);
console.log('CTA:', analysis.ctaType, analysis.ctaDestinationUrl);
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.