# Algrow API Documentation

> Base URL: https://api.algrow.online
> All plans: Channel search, scraping, and data endpoints
> Professional or Ultimate: Text-to-speech and voice generation endpoints

## Authentication

All endpoints require a valid API key via:
- Header: `Authorization: Bearer algrow_...`

---

## GET /api/health

Health check endpoint. Requires authentication. Returns your active/total job counts.

**Response:**
```json
{
  "status": "healthy",
  "active_jobs": 1,
  "total_jobs": 5,
  "max_concurrent": 5
}
```

---

## GET /api/voices

List available TTS voices. Supports filtering by gender, language, accent, and age.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| search | string | — | Search voices by name, labels, or description |
| gender | string | — | Filter: male, female |
| language | string | — | Filter by language (e.g. English, Spanish) |
| accent | string | — | Filter by accent (e.g. British, American) |
| age | string | — | Filter: young, middle_aged, old |
| sort | string | trending | Sort: trending, name, newest |
| page | integer | 0 | Page number (zero-indexed) |
| page_size | integer | 30 | Results per page (max 100) |

**Response:**
```json
{
  "success": true,
  "voices": [
    {
      "voice_id": "pNInz6obpgDQGcFmaJgB",
      "name": "Adam",
      "gender": "male",
      "accent": "American",
      "age": "middle_aged",
      "language": "English",
      "use_case": "narration",
      "description": "Deep, authoritative voice",
      "preview_url": "https://audio.algrow.online/previews/adam.mp3",
      "category": "generated"
    }
  ],
  "has_more": true
}
```

---

## POST /api/generate-simple

Generate text-to-speech audio. Async — returns a job_id immediately.

**Content-Type:** multipart/form-data

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| script | string | Yes | — | Text to convert. Max length is per-plan (ElevenLabs: Starter 60k, Professional 100k, Ultimate 200k chars; Stealth: Starter 30k, Professional 45k, Ultimate 100k chars) |
| voice_id | string | Yes | — | Voice ID from /api/voices or /api/voices/stealth |
| provider | string | No | elevenlabs | TTS provider: "elevenlabs" or "stealth" |
| voice_name | string | No | (voice_id) | Display name for the voice (used in auto-generated filenames) |
| custom_title | string | No | — | Custom filename title for the generated audio |
| model_id | string | No | eleven_multilingual_v2 | TTS model (ElevenLabs only) |
| stability | float | No | 0.5 | Voice stability 0-1 (ElevenLabs only) |
| similarity_boost | float | No | 0.5 | Voice similarity 0-1 (ElevenLabs only) |
| style | float | No | 0.0 | Style exaggeration 0-1 (ElevenLabs only) |
| speed | float | No | 1.0 | Speed 0.7-1.2 (ElevenLabs only) |
| generate_srt | boolean | No | false | Generate SRT subtitle file (ElevenLabs only) |

**Response:**
```json
{
  "success": true,
  "job_id": "a5358a1c-...",
  "status": "pending",
  "status_detail": "pending",
  "status_detail_message": "Processing",
  "message": "Generation queued. Worker will process it."
}
```

---

## GET /api/job-status/:job_id

Poll for any generation job status. Supports all job types: tts, caption_remover, sora_watermark, image, video.

**Response (completed — TTS job):**
```json
{
  "success": true,
  "job_id": "a5358a1c-...",
  "job_type": "tts",
  "status": "completed",
  "status_detail": "completed",
  "status_detail_message": "Completed",
  "created_at": 1711324800,
  "completed_at": 1711324830,
  "audio_url": "https://audio.algrow.online/voiceovers/abc123.mp3",
  "transcript_url": "https://audio.algrow.online/api/transcripts/abc123.txt"
}
```

**Response (completed — image job):**
```json
{
  "success": true,
  "job_id": "b7429c3e-...",
  "job_type": "image",
  "status": "completed",
  "image_urls": ["https://..."]
}
```

**Response (completed — video job):**
```json
{
  "success": true,
  "job_id": "c8539d4f-...",
  "job_type": "video",
  "status": "completed",
  "video_url": "https://..."
}
```

**Response (completed — caption_remover or sora_watermark job):**
```json
{
  "success": true,
  "job_id": "d9640e5g-...",
  "job_type": "caption_remover",
  "status": "completed",
  "output_url": "https://..."
}
```

**Response (failed):**
```json
{
  "success": true,
  "job_id": "a5358a1c-...",
  "job_type": "tts",
  "status": "failed",
  "error": "Description of what went wrong"
}
```

**Statuses:** pending, processing, completed, failed

---

## GET /api/jobs

List all your generation jobs. Returns all jobs sorted by creation time (newest first). No pagination or filtering parameters.

**Response:**
```json
{
  "success": true,
  "jobs": [
    {
      "id": "a5358a1c-...",
      "job_type": "tts",
      "provider": "elevenlabs",
      "status": "completed",
      "script_length": 1500,
      "created_at": 1711324800,
      "completed_at": 1711324830
    }
  ]
}
```

---

## GET /api/voices/stealth

List your custom cloned voices and default Stealth voices.

**Response:**
```json
{
  "success": true,
  "voices": [
    {
      "voice_id": "custom_abc123",
      "name": "My Custom Voice",
      "language": "en",
      "description": "A warm, natural voice",
      "tags": ["warm", "natural"],
      "is_cloned": true
    }
  ]
}
```

---

## POST /api/voices/clone

Clone a voice from an audio sample. Requires Professional or Ultimate plan.

**Content-Type:** multipart/form-data

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| displayName | string | Yes | Name for the cloned voice |
| audioFile | file | Yes | Audio file (MP3, WAV, M4A, OGG, WEBM — max 15MB) |
| langCode | string | No | Language code (default EN_US). Valid: EN_US, ZH_CN, KO_KR, JA_JP, RU_RU, IT_IT, ES_ES, PT_BR, DE_DE, FR_FR, AR_SA, PL_PL, NL_NL, HI_IN, HE_IL, AUTO |
| transcription | string | No | Transcription of the audio sample |
| description | string | No | Voice description |
| tags | string | No | Comma-separated tags for the voice |
| removeBackgroundNoise | boolean | No | Clean up background noise |

---

## DELETE /api/voices/stealth/:voice_id

Delete a custom cloned voice.

**Response:**
```json
{"success": true}
```

---

## POST /api/caption-remover

Remove captions/subtitles from a video. Costs 12 credits per minute of video (prorated). Max video duration: 90 seconds. Async job.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| video_url | string | Yes | URL of the video to process |

**Response:**
```json
{
  "success": true,
  "job_id": "a5358a1c-...",
  "status": "pending",
  "duration_seconds": 45.2,
  "credit_cost": 10,
  "message": "Caption removal queued. Poll /api/job-status/{job_id} for progress."
}
```

---

## POST /api/sora-watermark-remover

Remove Sora watermarks from AI-generated videos. Costs 2 credits. Async job.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| video_url | string | Yes | Must be a URL from sora.chatgpt.com |

**Response:**
```json
{
  "success": true,
  "job_id": "b7429c3e-...",
  "status": "pending",
  "credit_cost": 2,
  "message": "Sora watermark removal queued. Poll /api/job-status/{job_id} for progress."
}
```

---

## POST /api/generate-image

Generate an AI image. Credits vary by model. Async job.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| prompt | string | Yes | — | Image description |
| model | string | No | nano-banana-2 | Model: nano-banana-2 (2 credits), nano-banana-pro (3 credits), seedream-4.5-edit (2 credits), seedream-5.0-lite (2 credits) |
| aspect_ratio | string | No | 16:9 | Aspect ratio (e.g. 1:1, 16:9, 9:16) |
| reference_image_url | string | No | — | Reference image URL for style guidance |

---

## POST /api/generate-video

Generate an AI video. Credits vary by model and duration. Async job.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| prompt | string | Yes | — | Video description |
| model | string | No | sora-2 | Model: sora-2, kling-2.6, grok-image-to-video, veo3-fast |
| seconds | string | No | 4 | Duration in seconds (sora-2: 4/8/12) |
| size | string | No | 720x1280 | Resolution (e.g. 720x1280, 1920x1080) |
| input_reference_url | string | No | — | Reference image URL. Required for kling-2.6, grok-image-to-video, and veo3-fast |
| duration | string | No | 5 | Duration for kling-2.6 ("5" or "10") |
| sound | boolean | No | false | Enable audio generation (kling-2.6 only — doubles credit cost) |
| aspect_ratio | string | No | 9:16 | Aspect ratio (e.g. 9:16, 16:9) |

**Credit costs:**
- sora-2: 13 (4s), 18 (8s), 25 (12s)
- kling-2.6: 8 (5s), 15 (10s), 15 (5s+audio), 30 (10s+audio)
- grok-image-to-video: 3
- veo3-fast: 8

---

## POST /api/youtube-scraper

Scrape video data from a YouTube channel or single video. Async job — submit, then poll for results.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| url | string | Yes | — | YouTube channel URL or video URL |
| video_type | string | No | both | Type: shorts, videos, or both |
| sort | string | No | recent | Sort: recent or popular |
| max_videos | integer | No | 20 | Max videos to scrape (1-100) |
| include_transcripts | boolean | No | false | Include full video transcripts |
| include_comments | boolean | No | false | Include top comments per video |

**Response:**
```json
{
  "success": true,
  "job_id": 4521,
  "mode": "channel",
  "message": "Scraping job queued. Poll /api/youtube-scraper/{job_id} for results."
}
```

---

## GET /api/youtube-scraper/:job_id

Poll for YouTube scraping job results.

**Response (completed):**
```json
{
  "success": true,
  "job_id": 4521,
  "status": "completed",
  "result": {
    "total_videos": 10,
    "total_views": 1250000000,
    "total_likes": 42000000,
    "videos": [
      {
        "video_id": "dQw4w9WgXcQ",
        "title": "Video Title",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
        "view_count": 250000000,
        "like_count": 8500000,
        "comment_count": 2100000,
        "duration_seconds": 212,
        "duration_human": "3m 32s",
        "publish_date": "2025-10-15T14:00:00Z",
        "channel": "Channel Name",
        "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "transcript": "Full transcript text...",
        "comments": [
          {
            "author": "@user123",
            "text": "Great video!",
            "likes": 5200,
            "published_time": "2 months ago"
          }
        ]
      }
    ]
  }
}
```

---

## GET /api/terminated-channels/search

Search terminated/deleted YouTube channels. Returns channel metadata, growth metrics at time of termination, and top 3 videos per channel.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| q | string | **required** | Search query. Matches against channel titles and video titles. Comma-separated for multiple keywords. |
| languages | string | — | Filter by language (comma-separated, e.g. English,Spanish) |
| sort | string | date_desc | Sort: {field}_{asc|desc}. Fields: subs, views, videos, age, total_views, views_24h, subs_24h, views_48h, date, similarity |
| page | integer | 1 | Page number |
| per_page | integer | 20 | Results per page (max 50) |
| min_subs | integer | — | Minimum subscriber count |
| max_subs | integer | — | Maximum subscriber count |
| min_views | integer | — | Minimum total view count |
| max_views | integer | — | Maximum total view count |
| min_avg_views | integer | — | Minimum average views per video |
| max_avg_views | integer | — | Maximum average views per video |
| min_age | integer | — | Minimum channel age in days |
| max_age | integer | — | Maximum channel age in days |
| min_uploads | integer | — | Minimum number of videos |
| max_uploads | integer | — | Maximum number of videos |
| monetized | string | — | Filter: yes or no |
| min_views_24h | integer | — | Min views in last 24h before termination |
| max_views_24h | integer | — | Max views in last 24h before termination |
| min_views_48h | integer | — | Min views in last 48h before termination |
| max_views_48h | integer | — | Max views in last 48h before termination |

**Response:**
```json
{
  "success": true,
  "page": 1,
  "per_page": 20,
  "count": 20,
  "channels": [
    {
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "channel_title": "Channel Name",
      "subscriber_count": 340000,
      "view_count": 95000000,
      "avg_views_per_video": 2100000,
      "total_videos": 45,
      "primary_language": "English",
      "monetized": true,
      "is_low_quality": false,
      "thumbnail_url": "https://...",
      "first_upload_date": "2025-06-12",
      "terminated_date": "2026-03-10",
      "terminated_days_ago": 15,
      "view_increase_24h": 120000,
      "sub_increase_24h": 800,
      "view_increase_48h": 210000,
      "sub_increase_48h": 1400,
      "similarity_score": 85,
      "recent_videos": [
        {
          "video_id": "abc123",
          "title": "Top Video Title",
          "view_count": 12000000,
          "thumbnail_url": "https://...",
          "url": "https://www.youtube.com/watch?v=abc123"
        }
      ]
    }
  ]
}
```

---

## GET /api/channel-trends

Browse top-growing Shorts or longform channels ranked by 24h / 48h / 7d view or subscriber deltas. This is the same data source powering Algrow's Channel Trends page. Server-side base filters are always enforced (min subs/views floors, excludes flagged slop and music for longform) and cannot be bypassed by callers.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| content_type | string | shorts | Content type: "shorts" or "longform" |
| metric | string | views | Ranking metric: "views", "subs", "views_48h", "subs_48h", "views_7d", "subs_7d", "similarity". `similarity` only applies when `q` is supplied. |
| q | string | — | Keyword or @handle to narrow the leaderboard. Comma-separated for multiple terms; prefix with `-` to exclude. Uses embedding similarity under the hood. |
| page | integer | 1 | Page number (1-indexed, max 20) |
| per_page | integer | 50 | Results per page (max 50) |
| languages | string | — | Filter by language (comma-separated, e.g. English,Spanish) |
| min_subs / max_subs | integer | — | Subscriber count range |
| min_avg_views / max_avg_views | integer | — | Average views per video range |
| min_age / max_age | integer | — | Channel age in days range |
| min_videos / max_videos | integer | — | Number of videos range |
| remove_low_quality | boolean | — | Exclude channels flagged as low quality |
| remove_music | boolean | — | Exclude music channels (longform only) |

**Response:** `recent_videos[].url` uses `youtube.com/shorts/<id>` for shorts, `youtube.com/watch?v=<id>` for longform.

```json
{
  "success": true,
  "content_type": "shorts",
  "metric": "views",
  "page": 1,
  "per_page": 50,
  "count": 50,
  "has_more": true,
  "channels": [
    {
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "channel_title": "Channel Name",
      "url": "https://www.youtube.com/channel/UCxxxxxxxxxxxxxxxxxxxxxx",
      "thumbnail_url": "https://...",
      "subscriber_count": 125000,
      "primary_language": "English",
      "view_increase_24h": 215000,
      "sub_increase_24h": 420,
      "view_increase_48h": 410000,
      "sub_increase_48h": 820,
      "view_increase_7d": 1450000,
      "sub_increase_7d": 3100,
      "similarity_score": null,
      "recent_videos": [
        {"video_id": "abc123", "url": "https://www.youtube.com/shorts/abc123"}
      ]
    }
  ]
}
```

---

## GET /api/channels/search

Search Shorts channels with semantic AI search, keyword matching, and advanced filters. Returns channel metadata, growth metrics, and recent videos.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| q | string | **required** | Search query. Pass a channel name, @handle, or YouTube channel URL to find similar competitors. Comma-separated for multiple, prefix with - to exclude. |
| languages | string | — | Filter by language (comma-separated, e.g. English,Spanish) |
| sort | string | subs_desc | Sort: {field}_{asc\|desc}. Fields: subs, views, videos, age, added, views_24h, subs_24h, views_48h, similarity |
| page | integer | 1 | Page number (1-indexed, max 20) |
| per_page | integer | 20 | Results per page (max 50) |
| min_subs / max_subs | integer | — | Subscriber count range |
| min_avg_views / max_avg_views | integer | — | Average views per video range |
| min_age / max_age | integer | — | Channel age in days range |
| min_uploads / max_uploads | integer | — | Number of videos range |
| min_views / max_views | integer | — | Total view count range |
| min_views_24h / max_views_24h | integer | — | Views gained in last 24 hours range |
| min_views_48h / max_views_48h | integer | — | Views gained in last 48 hours range |
| min_days_added / max_days_added | integer | — | Days since channel was added to Algrow |

**Response:**
```json
{
  "success": true,
  "page": 1,
  "per_page": 20,
  "count": 20,
  "channels": [
    {
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "channel_title": "Channel Name",
      "subscriber_count": 150000,
      "avg_views_per_video": 500000,
      "total_videos": 120,
      "channel_age_days": 365,
      "view_count": 60000000,
      "primary_language": "English",
      "thumbnail_url": "https://...",
      "view_increase_24h": 50000,
      "sub_increase_24h": 200,
      "view_increase_48h": 95000,
      "similarity_score": 82,
      "recent_videos": [
        {
          "video_id": "abc123",
          "title": "Video Title",
          "view_count": 2000000,
          "upload_date": "2026-03-20",
          "thumbnail_url": "https://...",
          "url": "https://www.youtube.com/shorts/abc123"
        }
      ]
    }
  ]
}
```

---

## GET /api/longform-channels/search

Search Longform channels with semantic AI search, keyword matching, and advanced filters. Returns channel metadata, growth metrics, monetization status, and recent videos with duration.

**Query Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| q | string | **required** | Search query. Pass a channel name, @handle, or YouTube channel URL to find similar competitors. Comma-separated for multiple, prefix with - to exclude. |
| languages | string | — | Filter by language (comma-separated, e.g. English,Spanish) |
| sort | string | subs_desc | Sort: {field}_{asc\|desc}. Fields: subs, views, videos, age, total_views, added, views_24h, subs_24h, views_48h, similarity |
| page | integer | 1 | Page number (1-indexed, max 20) |
| per_page | integer | 20 | Results per page (max 50) |
| min_subs / max_subs | integer | — | Subscriber count range |
| min_avg_views / max_avg_views | integer | — | Average views per video range |
| min_age / max_age | integer | — | Channel age in days range |
| min_uploads / max_uploads | integer | — | Number of videos range |
| min_duration / max_duration | integer | — | Average video duration in seconds range |
| monetized | string | — | Filter by monetization: "yes" or "no" |
| min_views_24h / max_views_24h | integer | — | Views gained in last 24 hours range |
| min_views_48h / max_views_48h | integer | — | Views gained in last 48 hours range |
| min_days_added / max_days_added | integer | — | Days since channel was added to Algrow |

**Response:**
```json
{
  "success": true,
  "page": 1,
  "per_page": 20,
  "count": 20,
  "channels": [
    {
      "id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "name": "Channel Name",
      "subscriber_count": 500000,
      "avg_views_per_video": 200000,
      "total_videos": 80,
      "upload_day": 730,
      "view_count": 16000000,
      "primary_language": "English",
      "profile_picture": "https://...",
      "monetized": true,
      "url": "https://www.youtube.com/@ChannelName",
      "views_24h": 30000,
      "subs_24h": 150,
      "views_48h": 55000,
      "similarity_score": 76,
      "recent_videos": [
        {
          "video_id": "xyz789",
          "title": "Video Title",
          "view_count": 500000,
          "upload_date": "2026-03-18",
          "thumbnail_url": "https://...",
          "url": "https://www.youtube.com/watch?v=xyz789",
          "duration": 612
        }
      ]
    }
  ]
}
```

---

## GET|POST /api/viral-videos/search

Search for viral videos across Shorts and Longform channels, find videos similar to a specific video, or browse by filters alone. Filter by video views, channel size, growth metrics, upload recency, language, and outlier score. Accepts parameters via query string (GET) or JSON body (POST). `q`, `video_id`, and `video_url` are all optional — omit them to browse by filters alone (e.g. "biggest outliers from the last 7 days").

**Query Parameters / JSON Body:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| q | string | — | Search query. Also accepts channel IDs (UC...), @handles, bare video IDs, channel URLs, and video URLs. Alias: `search`. Optional — omit along with `video_id` / `video_url` to browse by filters alone. |
| video_id | string | — | YouTube video ID (e.g. "dQw4w9WgXcQ"). Finds similar videos by title. Optional. |
| video_url | string | — | YouTube video URL (watch, shorts, or youtu.be link). Optional. |
| content_type | string | shorts | Content type: "shorts" or "longform" |
| channel_ids | string/array | — | Comma-separated channel IDs (or JSON array) to filter by. Only returns videos from these channels. |
| languages | string | — | Filter by language (comma-separated, e.g. English,Spanish) |
| sort_by | string | views | Sort: "views", "recent", "upload_date", "similarity" (requires `q`/`video_id`/`video_url`), "outlier_score" (biggest over-performers — views vs channel average) |
| page | integer | 1 | Page number (1-indexed, max 20) |
| per_page | integer | 1 | Results per page (max 50) |
| min_similarity | integer | — | Minimum similarity score filter (applied post-query). Default 0.55 for thumbnail-based searches. |
| min_video_views / max_video_views | integer | — | Video view count range |
| min_subs / max_subs | integer | — | Channel subscriber count range |
| min_uploads / max_uploads | integer | — | Channel video count range |
| min_channel_age / max_channel_age | integer | — | Channel age in days range |
| min_upload_date / max_upload_date | integer | — | Upload date range (days ago, 0 = today) |
| min_duration / max_duration | integer | — | Video duration in minutes range (longform only) |
| min_views_24h / max_views_24h | integer | — | Channel views gained in last 24h (shorts only) |
| min_views_48h / max_views_48h | integer | — | Channel views gained in last 48h (shorts only) |
| min_outlier_score / max_outlier_score | float | — | Outlier score range. `outlier_score` = video's view count ÷ channel's average views per video (e.g. `2.5` = video got 2.5× the channel's typical views). Use to surface videos over-performing their channel. |

**Response:** Each video includes an `outlier_score` field (float multiplier; may be `null` for brand-new uploads before the channel average has been computed).

```json
{
  "success": true,
  "content_type": "shorts",
  "page": 1,
  "per_page": 1,
  "count": 1,
  "has_more": true,
  "videos": [
    {
      "video_id": "abc123",
      "title": "Video Title",
      "channel_name": "Channel Name",
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "view_count": 5000000,
      "outlier_score": 8.5,
      "thumbnail_url": "https://i.ytimg.com/vi/abc123/maxresdefault.jpg",
      "upload_date": "2026-03-25",
      "url": "https://www.youtube.com/shorts/abc123",
      "subscriber_count": 200000,
      "channel_thumbnail": "https://...",
      "duration": null,
      "view_increase_24h": 150000,
      "view_increase_48h": 280000,
      "similarity_score": 89
    }
  ]
}
```

---

## POST /api/thumbnail-search

Search for longform videos by thumbnail similarity. Provide a YouTube video URL, an image URL, or a text description to find videos with visually similar thumbnails using similarity matching.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| image_url | string | One of these three | — | URL of a thumbnail image to search with |
| video_url | string | One of these three | — | YouTube video URL (watch, shorts, or youtu.be link) |
| q | string | One of these three | — | Text description of thumbnail style (e.g. "before and after transformation") |
| limit | integer | No | 20 | Max results to return (1-50) |
| min_similarity | float | No | 0.55 | Minimum similarity threshold (0-1). Floor is 0.55. |
| min_views | integer | No | — | Minimum video view count filter |
| max_views | integer | No | — | Maximum video view count filter |
| min_upload_date | integer | No | — | Newest allowed upload (days ago, 0 = today) |
| max_upload_date | integer | No | — | Oldest allowed upload (days ago, e.g. 365 = 1 year) |

**Response:**
```json
{
  "success": true,
  "count": 10,
  "has_more": false,
  "videos": [
    {
      "video_id": "abc123",
      "title": "Video Title",
      "channel_name": "Channel Name",
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "view_count": 1500000,
      "thumbnail_url": "https://i.ytimg.com/vi/abc123/maxresdefault.jpg",
      "upload_date": "2026-03-20",
      "url": "https://www.youtube.com/watch?v=abc123",
      "duration": 612,
      "subscriber_count": 85000,
      "similarity_score": 78
    }
  ]
}
```

---

## POST /api/terminated-thumbnail-search

Search terminated/deleted channel videos by thumbnail similarity. Same as `/api/thumbnail-search` but searches the terminated channels archive instead of active longform channels.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| image_url | string | One of these three | — | URL of a thumbnail image to search with |
| video_url | string | One of these three | — | YouTube video URL (watch, shorts, or youtu.be link) |
| q | string | One of these three | — | Text description of thumbnail style (e.g. "before and after transformation") |
| limit | integer | No | 20 | Max results to return (1-50) |
| min_similarity | float | No | 0.55 | Minimum similarity threshold (0-1). Floor is 0.55. |
| min_views | integer | No | — | Minimum video view count filter |
| max_views | integer | No | — | Maximum video view count filter |

**Response:**
```json
{
  "success": true,
  "count": 10,
  "has_more": false,
  "videos": [
    {
      "video_id": "abc123",
      "title": "Video Title",
      "channel_name": "Channel Name",
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "view_count": 1500000,
      "thumbnail_url": "https://audio.algrow.online/thumbnails/abc123.jpg",
      "url": "https://www.youtube.com/watch?v=abc123",
      "subscriber_count": 85000,
      "similarity_score": 78
    }
  ]
}
```

---

## POST /api/upload-text

Upload a text string and receive a hosted URL. Useful for storing transcripts or other text content.

**Content-Type:** application/json

**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| text | string | Yes | — | Text content to upload |
| filename | string | No | transcript.txt | Filename for the hosted file |

**Response:**
```json
{
  "success": true,
  "url": "https://audio.algrow.online/api/transcripts/abc123_transcript.txt"
}
```

---

## Rate Limits

| Bucket | Requests/min |
|--------|-------------|
| All endpoints | 30 |
| Status/polling endpoints (/api/job-status, /api/health, /api/jobs) | 40 |

Rate limit is the same for all plans (Starter, Professional, Ultimate).

---

## Credits

| Feature | Cost |
|---------|------|
| TTS Generation | 1 credit per character of script |
| Caption Removal | 12 credits per minute of video (prorated, max 90s) |
| Sora Watermark Removal | 2 credits |
| Image Generation | 2-3 credits (varies by model — see /api/generate-image) |
| Video Generation | 3-30 credits (varies by model and duration — see /api/generate-video) |
| YouTube Scraper | 1 credit per job |
| Channel Search | Free (included with plan) |
| Terminated Channel Search | Free (included with plan) |
| Thumbnail Search | Free (included with plan) |
| Viral Video Search | Free (included with plan) |

---

## Error Codes

| Code | Meaning |
|------|---------|
| 400 | Bad request — invalid parameters |
| 401 | Unauthorized — missing or invalid API key |
| 403 | Forbidden — plan upgrade required |
| 404 | Not found — resource doesn't exist |
| 429 | Rate limited — too many requests |
| 500 | Server error — try again later |

Error response format:
```json
{
  "success": false,
  "error": "Description of what went wrong"
}
```