API Documentation

Quickstart

Get your first audio file in under 60 seconds.

1

Get your API key

Go to Settings → API Keys in your Algrow dashboard and generate a key.

2

Submit a job

Send a POST to /api/generate-simple with your script and voice ID.

3

Get your audio

Poll /api/job-status/:id until complete. The response includes a permanent audio URL.

Try it now

# 1. Submit a generation curl -X POST "https://api.algrow.online/api/generate-simple" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "script=Hello, welcome to our channel. This is a test of the Algrow TTS API." \ -F "voice_id=21m00Tcm4TlvDq8ikWAM" # 2. Poll for completion (replace JOB_ID with the job_id from step 1) curl "https://api.algrow.online/api/job-status/JOB_ID" \ -H "Authorization: Bearer YOUR_API_KEY"

How It Works

The API is fully asynchronous. You submit a generation request and receive a job ID immediately. Audio is generated in the background — poll the status endpoint until it's ready.

1. SubmitPOST /api/generate-simple

→

2. Receivejob_id returned instantly

→

3. PollGET /api/job-status/:id

→

4. DownloadPermanent audio URL

Content-Type: All POST requests use multipart/form-data encoding. Send parameters as form fields, not JSON.

Audio URLs are permanent. Completed audio files are stored on our CDN at audio.algrow.online and will not expire. You can safely store and reference these URLs long-term.

Authentication

All endpoints (except /api/health) require a valid API key. Include it using one of these methods:

Authorization Header (Recommended)

Authorization: Bearer algrow_...

Query Parameter

?api_key=algrow_...

Form Data Field

api_key=algrow_...

Sent in the multipart form body

Keep your API key secret. Do not expose it in client-side code, public repositories, or URLs that may be logged. If compromised, regenerate it immediately from your dashboard.

Text-to-Speech

Generate high-quality TTS audio programmatically. Submit a script, choose a voice, and receive a permanent hosted audio URL. Uses character-based credits (see Credits & Billing).

GET /api/voices

Browse and search available ElevenLabs voices. Returns voice IDs you can use with provider=elevenlabs. For Stealth voices, use /api/voices/stealth instead.

Headers

Name	Type	Required	Description
Authorization	string	Required	Bearer token: `Bearer YOUR_API_KEY`

Query Parameters

Name	Type	Required	Default	Description
search	string	Optional	—	Search by voice name or labels
gender	string	Optional	—	Filter by gender: `male`, `female`, or `neutral`
age	string	Optional	—	Filter by age: `young`, `middle_aged`, or `old`
language	string	Optional	—	Language code (e.g. `en`, `es`, `fr`)
accent	string	Optional	—	Filter by accent (e.g. `american`, `british`)
sort	string	Optional	trending	Sort by: `trending`, `created_date`, `usage_character_count_1y`
page_size	integer	Optional	30	Results per page (max 100)
page	integer	Optional	0	Page number (0-indexed)

Example Request

# Browse trending voices curl "https://api.algrow.online/api/voices?sort=trending&page_size=10" \ -H "Authorization: Bearer YOUR_API_KEY" # Search for female English voices curl "https://api.algrow.online/api/voices?search=narrator&gender=female&language=en" \ -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "voices": [
    {
      "voice_id": "EkK5I93UQWFDigLMpZcX",
      "name": "James - Husky, Engaging and Bold",
      "gender": "male",
      "age": "middle_aged",
      "accent": "american",
      "language": "en",
      "description": "A slightly husky and bassy voice...",
      "preview_url": "https://...",
      "category": "high_quality",
      "use_case": "narrative_story"
    }
  ],
  "has_more": true
}

POST /api/generate-simple

Create a text-to-speech generation job. Returns a job_id immediately. The audio is generated asynchronously — poll /api/job-status/:job_id to check progress and retrieve the audio URL when complete.

Headers

Name	Type	Required	Description
Authorization	string	Required	Bearer token: `Bearer YOUR_API_KEY`
Content-Type	string	Auto	Set automatically by `curl -F`. If manual: `multipart/form-data`

Request Parameters (form-data)

Name	Type	Required	Default	Description
script	string	Required	—	Text to convert to speech. Maximum 200,000 characters.
voice_id	string	Required	—	ElevenLabs voice ID. Example: `21m00Tcm4TlvDq8ikWAM` (Rachel)
provider	string	Optional	elevenlabs	TTS engine. Values: `elevenlabs`, `stealth`
model_id	string	Optional	eleven_multilingual_v2	Model to use. Also available: `eleven_v3`, `eleven_turbo_v2_5`, `eleven_flash_v2_5`, `eleven_turbo_v2`, `eleven_flash_v2`
stability	float	Optional	0.5	Voice consistency. Higher = more stable, lower = more expressive. Range: 0.0 – 1.0
similarity_boost	float	Optional	0.5	How closely to match the original voice. Range: 0.0 – 1.0
style	float	Optional	0.0	Speaking style exaggeration. Higher values amplify the voice's style. Range: 0.0 – 1.0
speed	float	Optional	1.0	Playback speed multiplier. Range: 0.7 – 1.2
voice_name	string	Optional	voice_id	Human-readable label for this voice (for your reference only)
custom_title	string	Optional	—	Custom filename for the output MP3 (without extension)
generate_srt	string	Optional	false	Set to `true` to generate an SRT subtitle file (ElevenLabs only)
temperature	float	Optional	1.1	Voice expressiveness (Stealth only). Higher = more expressive.
speaking_rate	float	Optional	1.0	Speaking speed multiplier (Stealth only).

Provider-specific parameters:
When provider=stealth: only temperature and speaking_rate are used. Parameters stability, similarity_boost, style, speed, and model_id are ignored.
When provider=elevenlabs (default): only stability, similarity_boost, style, speed, and model_id are used. Parameters temperature and speaking_rate are ignored.

Stealth model: Uses stealth-tts-1.5-max — the most expressive model. Max input: 200,000 characters (auto-chunked at ~1,900 char boundaries). Output: MP3, uploaded to CDN.

Example Request (ElevenLabs)

curl -X POST "https://api.algrow.online/api/generate-simple" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "script=Hello, welcome to our channel." \ -F "voice_id=21m00Tcm4TlvDq8ikWAM" \ -F "provider=elevenlabs" \ -F "stability=0.7" \ -F "similarity_boost=0.8"

Example Request (Stealth)

curl -X POST "https://api.algrow.online/api/generate-simple" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "script=Hello, welcome to our channel." \ -F "voice_id=Edward" \ -F "provider=stealth" \ -F "temperature=1.1" \ -F "speaking_rate=1.0"

Response 200

{
  "success": true,
  "job_id": "300040",
  "status": "pending",
  "status_detail": "pending",
  "status_detail_message": "Processing",
  "message": "Generation queued. Worker will process it.",
  "payload": {
    "text": "Hello, welcome to our channel.",
    "voice_id": "21m00Tcm4TlvDq8ikWAM",
    "voice_name": "21m00Tcm4TlvDq8ikWAM",
    "settings": { ... }
  }
}

Response Fields

Field	Type	Description
success	boolean	Whether the request was accepted
job_id	string	Unique job identifier. Use this to poll for status.
status	string	Current job status: `pending`
status_detail_message	string	Human-readable status message
message	string	Informational message
payload	object	Echo of the submitted parameters (text, voice_id, settings, etc.)

200 Queued 400 Validation error 401 Auth failed 402 No credits 403 Plan required 429 Too busy 500 Server error

GET /api/job-status/:job_id

Retrieve the current status and result of a generation job. Poll this endpoint every 2–3 seconds until status is completed or failed. Typical generation time is 3–15 seconds depending on script length.

Path Parameters

Name	Type	Required	Description
job_id	string	Required	The `job_id` returned from `POST /api/generate-simple`

Example Request

curl "https://api.algrow.online/api/job-status/300040" \ -H "Authorization: Bearer YOUR_API_KEY"

Response — In Progress

{
  "success": true,
  "job_id": "300040",
  "status": "processing",
  "status_detail": "processing",
  "status_detail_message": "Processing",
  "created_at": 1772482202.525
}

Response — Completed

{
  "success": true,
  "job_id": "300040",
  "status": "completed",
  "status_detail": "completed",
  "status_detail_message": "Completed",
  "created_at": 1772482202.525,
  "completed_at": 1772482210.831,
  "audio_url": "https://audio.algrow.online/elevenlabs/tts/user123/300040.mp3",
  "transcript_url": "https://audio.algrow.online/elevenlabs/tts/user123/transcript_300040.srt"
}

Response — Failed

{
  "success": true,
  "job_id": "300040",
  "status": "failed",
  "status_detail": "failed",
  "status_detail_message": "Failed",
  "created_at": 1772482202.525,
  "completed_at": 1772482215.100,
  "error": "Async job failed: [TERMS_OF_SERVICE_VIOLATION] The text you are trying to use may violate our Terms of Service and has been blocked.",
  "error_code": "TERMS_OF_SERVICE_VIOLATION",
  "error_message": "The text you are trying to use may violate our Terms of Service and has been blocked."
}

Response Fields

Field	Type	Description
success	boolean	Always `true` if the job was found
job_id	string	The job identifier
status	string	One of: `pending`, `processing`, `completed`, `failed`
status_detail_message	string	Human-readable status: "Processing", "Completed", or "Failed"
created_at	float	Unix timestamp when the job was created
completed_at	float	Unix timestamp when the job finished (only present when done)
audio_url	string	Permanent URL to the MP3 file. After generation, audio is uploaded to Cloudflare R2 and served via our CDN at `audio.algrow.online` — this URL will not expire. (Only when `status=completed`)
transcript_url	string	Permanent URL to the SRT subtitle file. Only present when `generate_srt=true` was set and `status=completed`.
error	string	Error description (only when `status=failed`)
error_code	string	Machine-readable error code, e.g. `TERMS_OF_SERVICE_VIOLATION` (only when `status=failed`, if available)
error_message	string	Human-readable error message from the provider (only when `status=failed`, if available)

Status lifecycle: pending → processing → completed or failed. Typical completion time is 3–15 seconds.

200 Success 401 Auth failed 404 Job not found

GET /api/jobs

List your generation jobs, sorted by creation time (newest first). Returns only jobs belonging to the authenticated user. Useful for debugging and monitoring your recent generations.

Example Request

curl "https://api.algrow.online/api/jobs" \ -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "jobs": [
    {
      "id": "300040",
      "provider": "elevenlabs",
      "status": "completed",
      "script_length": 340,
      "created_at": 1772482202.525,
      "completed_at": 1772482210.831
    }
  ]
}

GET /api/health

Check API health and view your current job counts. No authentication required. Use this to verify the API is online and check how many concurrent slots you have available.

Example Request

curl "https://api.algrow.online/api/health" \ -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "status": "healthy",
  "active_jobs": 2,
  "total_jobs": 15
}

Voice Management

Manage your Stealth TTS voices — list available voices, clone custom voices from audio samples, and delete cloned voices.

GET /api/voices/stealth

List available Stealth voices. Returns built-in voices plus any voices you have cloned.

Example Request

curl "https://api.algrow.online/api/voices/stealth" \ -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "voices": [
    {
      "voice_id": "Edward",
      "name": "Edward",
      "language": "en",
      "description": "",
      "tags": [],
      "is_cloned": false
    },
    {
      "voice_id": "default-xxx__my-custom-voice",
      "name": "My Custom Voice",
      "language": "en",
      "description": "Cloned from sample",
      "tags": ["custom"],
      "is_cloned": true
    }
  ]
}

Response Fields

Field	Type	Description
voice_id	string	Use this as the `voice_id` parameter in `/api/generate-simple`
name	string	Display name of the voice
language	string	Language code (e.g. `en`, `es`, `de`)
is_cloned	boolean	Whether this voice was cloned by you

200 Success 401 Auth failed

POST /api/voices/clone

Clone a custom Stealth voice from an audio sample. Upload up to 30 seconds of clear speech audio. The cloned voice can then be used with provider=stealth in the generate endpoint.

Clone limits by plan: Starter — 5 clones, Professional — 15 clones, Ultimate — unlimited.

Request Parameters (multipart form-data)

Name	Type	Required	Default	Description
displayName	string	Required	—	Name for the cloned voice
audioFile	file	Required	—	Audio sample (MP3, WAV, M4A, OGG, WEBM). Max 15MB, max 30 seconds.
langCode	string	Optional	EN_US	Language of the audio. Values: `EN_US`, `ES_ES`, `FR_FR`, `DE_DE`, `PT_BR`, `IT_IT`, `JA_JP`, `KO_KR`, `ZH_CN`, `RU_RU`, `AR_SA`, `PL_PL`, `NL_NL`, `HI_IN`, `HE_IL`
transcription	string	Optional	—	Text transcription of the audio sample (improves clone quality)
description	string	Optional	—	Description of the voice
tags	string	Optional	—	Comma-separated tags (e.g. `narrator,deep`)
removeBackgroundNoise	string	Optional	false	Set to `true` to remove background noise from the sample

Example Request

curl -X POST "https://api.algrow.online/api/voices/clone" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "displayName=My Narrator" \ -F "langCode=EN_US" \ -F "audioFile=@sample.mp3" \ -F "transcription=Hello, this is a sample of my voice." \ -F "removeBackgroundNoise=true"

Response

{
  "success": true,
  "voice": {
    "voice_id": "default-xxx__my-narrator",
    "name": "My Narrator",
    "language": "EN_US",
    "description": "",
    "tags": []
  }
}

200 Created 400 Validation error 401 Auth failed 403 Plan / limit

DELETE /api/voices/stealth/:voice_id

Delete a cloned Stealth voice. Only voices you own can be deleted. This action is permanent.

Path Parameters

Name	Type	Required	Description
voice_id	string	Required	The `voice_id` of the cloned voice to delete

Example Request

curl -X DELETE "https://api.algrow.online/api/voices/stealth/default-xxx__my-narrator" \ -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true
}

200 Deleted 401 Auth failed 404 Not found

Media Generation

Generate images, videos, and remove captions/watermarks from videos. All media endpoints use studio credits, require a Professional or Ultimate plan, and follow the same async job pattern — submit a request, receive a job_id, then poll /api/job-status/:job_id for results.

POST /api/caption-remover

Remove captions and watermarks from a video. Accepts a publicly accessible video URL, processes it via AI, and returns a cleaned video uploaded to CDN. Credits are deducted upfront and refunded automatically if processing fails.

Request Body (JSON)

Name	Type	Required	Description
video_url	string	Required	Publicly accessible URL of the video to process

Cost: 12 studio credits per minute of video (0.2 credits per second, rounded up). Max duration: 90 seconds. Processing can take up to 30 minutes depending on video length.

Example Request

curl -X POST "https://api.algrow.online/api/caption-remover" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"video_url": "https://example.com/my-video.mp4"}'

Response 200

{
  "success": true,
  "job_id": "a5358a1c-388d-47a3-989e-755291031d77",
  "status": "pending",
  "credit_cost": 6,
  "message": "Caption removal queued. Poll /api/job-status/{job_id} for progress."
}

Completed Job Response (via /api/job-status/:job_id)

{
  "success": true,
  "job_id": "a5358a1c-388d-47a3-989e-755291031d77",
  "job_type": "caption_remover",
  "status": "completed",
  "output_url": "https://audio.algrow.online/api/video/caption_remover_abc123.mp4",
  "completed_at": 1774200779.08
}

200 Queued 400 Missing video_url 401 Auth failed 402 No credits 403 Plan required 429 Too busy

POST /api/sora-watermark-remover

Remove the OpenAI watermark from a Sora 2 video. Accepts a Sora video URL (sora.chatgpt.com/p/s_...), processes it via AI, and returns a cleaned video uploaded to CDN. Credits are deducted upfront and refunded automatically if processing fails.

Request Body (JSON)

Name	Type	Required	Description
video_url	string	Required	Sora 2 video URL. Must be from `sora.chatgpt.com` (e.g. `https://sora.chatgpt.com/p/s_abc123...`)

Cost: 2 studio credits per request. Processing typically takes under 2 minutes.

Example Request

curl -X POST "https://api.algrow.online/api/sora-watermark-remover" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"video_url": "https://sora.chatgpt.com/p/s_abc123def456"}'

Response 200

{
  "success": true,
  "job_id": "b7429c3e-5a1f-4d8b-a90e-123456789abc",
  "status": "pending",
  "credit_cost": 2,
  "message": "Sora watermark removal queued. Poll /api/job-status/{job_id} for progress."
}

Completed Job Response (via /api/job-status/:job_id)

{
  "success": true,
  "job_id": "b7429c3e-5a1f-4d8b-a90e-123456789abc",
  "job_type": "sora_watermark",
  "status": "completed",
  "output_url": "https://audio.algrow.online/api/video/sora_watermark_xyz789.mp4",
  "completed_at": 1774200830.15
}

200 Queued 400 Missing/invalid URL 401 Auth failed 402 No credits 403 Pro/Ultimate required 429 Too busy

POST /api/generate-image

Generate AI images from a text prompt. Supports multiple models with optional reference images. Returns one or more image URLs uploaded to CDN. Credits are deducted upfront and refunded automatically if generation fails.

Request Body (JSON)

Name	Type	Required	Default	Description
prompt	string	Required	—	Text description of the image to generate
model	string	Optional	nano-banana-2	Image model. See model table below.
aspect_ratio	string	Optional	16:9	Output aspect ratio (e.g. `16:9`, `9:16`, `1:1`, `4:3`)
reference_image_url	string	Optional	—	URL of a reference image for style guidance. Required for `seedream-4.5-edit`.

Available Models

Model	Credits	Notes
`nano-banana-2`	2	Fast general-purpose generation (default)
`nano-banana-pro`	3	Higher quality, supports up to 8 reference images
`seedream-4.5-edit`	2	Image editing — requires `reference_image_url`
`seedream-5.0-lite`	2	Lightweight generation, optional reference

Example Request

curl -X POST "https://api.algrow.online/api/generate-image" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "a sunset over mountains, photorealistic", "model": "nano-banana-2", "aspect_ratio": "16:9"}'

Response 200

{
  "success": true,
  "job_id": "536c20ce-5ee6-4b8d-9f7f-3994014c896e",
  "status": "pending",
  "credits_used": 2,
  "message": "Image generation queued. Poll /api/job-status/{job_id} for progress."
}

Completed Job Response (via /api/job-status/:job_id)

{
  "success": true,
  "job_id": "536c20ce-5ee6-4b8d-9f7f-3994014c896e",
  "job_type": "image",
  "status": "completed",
  "image_urls": ["https://audio.algrow.online/api/images/user123/1774201509_0_5b0a0050.png"],
  "completed_at": 1774201512.99
}

200 Queued 400 Validation error 401 Auth failed 402 No credits 403 Plan required 429 Too busy

POST /api/generate-video

Generate AI videos from a text prompt. Supports multiple models including Sora, Kling, Grok, and Veo. Returns a video URL uploaded to CDN. Credits are deducted upfront and refunded automatically if generation fails.

Request Body (JSON)

Name	Type	Required	Default	Description
prompt	string	Required	—	Text description of the video to generate
model	string	Optional	sora-2	Video model. See model table below.
input_reference_url	string	Conditional	—	Reference image URL. Required for `kling-2.6`, `grok-image-to-video`, and `veo3-fast`.
seconds	string	Optional	4	Video duration in seconds (Sora only). Values: `4`, `8`, `12`
size	string	Optional	720x1280	Output resolution (Sora only). e.g. `720x1280`, `1280x720`
duration	string	Optional	5	Video duration (Kling only). Values: `5`, `10`
sound	boolean	Optional	false	Enable audio generation (Kling only). Doubles the credit cost.
aspect_ratio	string	Optional	9:16	Output aspect ratio (Veo only). e.g. `9:16`, `16:9`

Available Models

Model	Credits	Reference Image	Notes
`sora-2`	13 / 18 / 25	Optional	OpenAI Sora. Cost varies by duration: 4s / 8s / 12s
`kling-2.6`	8 – 30	Required	Image-to-video. Cost varies by duration and sound.
`grok-image-to-video`	3	Required	Grok image-to-video generation
`veo3-fast`	8	Required	Google Veo 3.1 Fast video generation

Example Request (Sora)

curl -X POST "https://api.algrow.online/api/generate-video" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "a cat walking through flowers", "model": "sora-2", "seconds": "4", "size": "720x1280"}'

Example Request (Kling with reference image)

curl -X POST "https://api.algrow.online/api/generate-video" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "person waving at camera", "model": "kling-2.6", "input_reference_url": "https://example.com/photo.jpg", "duration": "5"}'

Response 200

{
  "success": true,
  "job_id": "e58464d7-ae8d-41b2-8c52-79bac92b1bb9",
  "status": "pending",
  "credit_cost": 13,
  "message": "Video generation queued. Poll /api/job-status/{job_id} for progress."
}

Completed Job Response (via /api/job-status/:job_id)

{
  "success": true,
  "job_id": "e58464d7-ae8d-41b2-8c52-79bac92b1bb9",
  "job_type": "video",
  "status": "completed",
  "video_url": "https://audio.algrow.online/sora/videos/user123/video_abc123.mp4",
  "completed_at": 1774200881.01
}

Processing time: Video generation can take 30 seconds to 30 minutes depending on the model and duration. Poll /api/job-status/:job_id every 5 seconds for updates.

200 Queued 400 Validation error 401 Auth failed 402 No credits 403 Plan required 429 Too busy

GET /api/terminated-channels/search

Search terminated/deleted YouTube channels. Returns channel metadata, growth metrics at time of termination, and up to 3 top videos per channel. Supports keyword matching and advanced filters. Available on Professional and Ultimate plans only.

Query Parameters

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

Example Requests

# Search for terminated gaming channels
curl "https://api.algrow.online/api/terminated-channels/search?q=gaming&languages=English&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# High-sub terminated channels sorted by subscribers
curl "https://api.algrow.online/api/terminated-channels/search?min_subs=100000&sort=subs_desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Recently terminated channels
curl "https://api.algrow.online/api/terminated-channels/search?sort=date_desc&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "success": true,
  "page": 1,
  "per_page": 20,
  "count": 20,
  "channels": [
    {
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "channel_title": "Deleted Gaming Channel",
      "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://yt3.ggpht.com/...",
      "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": "Most Viewed Video Title",
          "view_count": 12000000,
          "thumbnail_url": "https://audio.algrow.online/thumbnails/...",
          "url": "https://www.youtube.com/watch?v=abc123"
        }
      ]
    }
  ]
}

Response Fields

Field	Type	Description
channel_id	string	YouTube channel ID
channel_title	string	Channel name at time of termination
subscriber_count	integer	Subscriber count at termination
view_count	integer	Total channel views at termination
avg_views_per_video	integer	Average views per video
total_videos	integer	Number of videos on the channel
primary_language	string	Detected content language
monetized	boolean	Whether the channel was monetized
is_low_quality	boolean	Whether the channel was flagged as low quality
thumbnail_url	string	Channel profile picture URL
first_upload_date	string	Date of the channel's first upload (ISO 8601)
terminated_date	string	Date the channel was terminated (ISO 8601)
terminated_days_ago	integer	Days since the channel was terminated
view_increase_24h	integer\|null	Views gained in last 24h before termination
sub_increase_24h	integer\|null	Subscribers gained in last 24h before termination
view_increase_48h	integer\|null	Views gained in last 48h before termination
sub_increase_48h	integer\|null	Subscribers gained in last 48h before termination
similarity_score	integer\|null	AI similarity score (0–100) when using `q` search
recent_videos	array	Top 3 videos by views with `video_id`, `title`, `view_count`, `thumbnail_url`, `url`

200 Success 401 Auth failed 403 Pro/Ultimate required 500 Server error

GET /api/viral-videos/search

Search for viral videos across Shorts and Longform channels. Filter by video views, channel size, growth metrics, upload recency, language, and more. Search supports keyword matching and similarity scoring.

Query Parameters

Name	Type	Required	Default	Description
content_type	string	Optional	shorts	Content type: `shorts` or `longform`
search	string	Optional	—	Search query. Matches video titles and channel names with similarity scoring.
languages	string	Optional	English	Filter by language. Comma-separated (e.g. `English,Spanish`). Defaults to English if omitted.
sort_by	string	Optional	views	Sort by: `views` (most viewed), `recent` (newest fetched), `upload_date` (newest uploaded), `similarity` (most similar, auto-selected when searching)
page	integer	Optional	1	Page number (1-indexed)
per_page	integer	Optional	20	Results per page (max 50)
min_video_views	integer	Optional	—	Minimum video view count
max_video_views	integer	Optional	—	Maximum video view count
min_subs	integer	Optional	—	Minimum channel subscriber count
max_subs	integer	Optional	—	Maximum channel subscriber count
min_uploads	integer	Optional	—	Minimum channel video count
max_uploads	integer	Optional	—	Maximum channel video count
min_channel_age	integer	Optional	—	Minimum channel age in days
max_channel_age	integer	Optional	—	Maximum channel age in days
min_upload_date	integer	Optional	—	Newest allowed upload (days ago, 0 = today)
max_upload_date	integer	Optional	—	Oldest allowed upload (days ago, e.g. 365 = 1 year)
min_duration	integer	Optional	—	Minimum video duration in minutes (longform only)
max_duration	integer	Optional	—	Maximum video duration in minutes (longform only)
min_views_24h	integer	Optional	—	Minimum channel views gained in last 24h (shorts only)
max_views_24h	integer	Optional	—	Maximum channel views gained in last 24h (shorts only)
min_views_48h	integer	Optional	—	Minimum channel views gained in last 48h (shorts only)
max_views_48h	integer	Optional	—	Maximum channel views gained in last 48h (shorts only)

Example Requests

# Find viral Shorts with 1M+ views from small channels
curl "https://api.algrow.online/api/viral-videos/search?content_type=shorts&min_video_views=1000000&max_subs=50000" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Longform videos uploaded in last 7 days, sorted by views
curl "https://api.algrow.online/api/viral-videos/search?content_type=longform&max_upload_date=7&sort_by=views" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search for cooking videos from channels under 100k subs
curl "https://api.algrow.online/api/viral-videos/search?search=cooking&max_subs=100000&languages=English" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "content_type": "shorts",
  "page": 1,
  "per_page": 20,
  "count": 20,
  "videos": [
    {
      "video_id": "dQw4w9WgXcQ",
      "title": "This cooking hack changed everything",
      "channel_name": "Chef Secrets",
      "channel_id": "UCxxxxxxxxxxxxxxxxxxxxxx",
      "view_count": 4200000,
      "thumbnail_url": "https://i.ytimg.com/vi/.../maxresdefault.jpg",
      "upload_date": "2026-03-15T00:00:00+00:00",
      "url": "https://www.youtube.com/shorts/dQw4w9WgXcQ",
      "subscriber_count": 32000,
      "duration": 58,
      "view_increase_24h": 180000,
      "view_increase_48h": 320000
    }
  ]
}

Response Fields (per video)

Field	Type	Description
video_id	string	YouTube video ID
title	string	Video title
channel_name	string	Channel name
channel_id	string	YouTube channel ID
view_count	integer	Total video views
thumbnail_url	string	Video thumbnail URL
upload_date	string\|null	Upload date (ISO 8601)
url	string	Full YouTube URL
subscriber_count	integer	Channel subscriber count
duration	integer\|null	Video duration in seconds
view_increase_24h	integer\|null	Channel views gained in last 24h (shorts with realtime filters only)
view_increase_48h	integer\|null	Channel views gained in last 48h (shorts with realtime filters only)
similarity_score	integer\|null	Similarity score (0–100) when using search. Higher = more similar.

200 Success 401 Auth failed 400 Invalid content_type 500 Server error

POST /api/youtube-scraper

Scrape video data from a YouTube channel or single video. Returns video metadata (title, views, likes, duration, thumbnails), with optional transcripts and comments. Async job — submit a request, then poll for results.

Request Body (JSON)

Name	Type	Required	Default	Description
url	string	Required	—	YouTube channel URL or video URL. Auto-detects single video vs. channel mode.
video_type	string	Optional	both	Type of videos to scrape: `shorts`, `videos`, or `both`
sort	string	Optional	recent	Sort order: `recent` or `popular`
max_videos	integer	Optional	20	Maximum videos to scrape (1–100)
include_transcripts	boolean	Optional	false	Include full video transcripts in the response
include_comments	boolean	Optional	false	Include top comments for each video

Example Request

# Scrape a channel's most popular videos with transcripts curl -X POST "https://api.algrow.online/api/youtube-scraper" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://www.youtube.com/@MrBeast", "video_type": "videos", "sort": "popular", "max_videos": 10, "include_transcripts": true }'

Response 200

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

200 Queued 400 Invalid URL 401 Auth failed 403 Pro/Ultimate required

GET /api/youtube-scraper/:job_id

Poll for the result of a YouTube scraping job. Returns pending or processing while running, and the full video data when completed.

Example Request

curl "https://api.algrow.online/api/youtube-scraper/4521" \ -H "Authorization: Bearer YOUR_API_KEY"

Completed Response 200

{
  "success": true,
  "job_id": 4521,
  "status": "completed",
  "created_at": "2026-03-24T10:30:00",
  "completed_at": "2026-03-24T10:31:15",
  "result": {
    "total_videos": 10,
    "total_views": 1250000000,
    "total_likes": 42000000,
    "videos": [
      {
        "video_id": "dQw4w9WgXcQ",
        "title": "Video Title Here",
        "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": "MrBeast",
        "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
        "transcript": "Full transcript text here...",
        "comments": [
          {
            "author": "@user123",
            "text": "Great video!",
            "likes": 5200,
            "published_time": "2 months ago"
          }
        ]
      }
    ]
  }
}

Response Fields (per video)

Field	Type	Description
video_id	string	YouTube video ID
title	string	Video title
url	string	Full YouTube URL
thumbnail	string	Thumbnail image URL (highest resolution available)
view_count	integer	Total views
like_count	integer	Total likes
comment_count	integer	Total comments
duration_seconds	integer	Video length in seconds
duration_human	string	Human-readable duration (e.g. “3m 32s”)
publish_date	string	Publish date (ISO 8601)
channel	string	Channel name
channel_id	string	YouTube channel ID
transcript	string\|null	Full transcript (only if `include_transcripts: true`)
comments	array\|null	Top comments (only if `include_comments: true`)

200 Success 401 Auth failed 404 Job not found

Rate Limits

The API enforces the following limits to ensure fair usage and service stability.

200,000

Max characters per request

~25 min

Max generation timeout

MP3

Output format (44.1kHz, 128kbps)

5

Max concurrent per user

Concurrent requests: Each user can have up to 5 active generations at a time. If you hit the limit, you will receive a 429 response — wait for some jobs to complete and retry.

Credits & Billing

Algrow uses two credit systems: TTS credits (character-based) for voice generation, and studio credits for media generation and video processing. Credits are checked before each job and only deducted after successful completion — you are never charged for failed jobs.

TTS Credits

1 credit = 1 character. Whitespace and punctuation count. A 500-character script costs 500 credits.

Package	Characters	Price	Per 1K chars
Starter	1,000,000	$6.00	$0.006
Creator	5,000,000	$25.00	$0.005
Studio	10,000,000	$45.00	$0.0045

Studio Credits

Studio credits are separate from TTS credits. They are deducted upfront and automatically refunded if a job fails.

Feature	Credits	Notes
Image Generation	2–3	Varies by model (see available models)
Video Generation	3–30	Varies by model and duration (see available models)
Caption Removal	12 per minute	0.2 per second, rounded up
Sora Watermark Removal	2	Per video

Insufficient credits? The API returns 402 Payment Required with the exact number of credits available and needed. Purchase more credits from your Algrow dashboard.

Error Handling

All errors follow a consistent format. Check success: false and read the error field for details.

Error Response Format

{
  "success": false,
  "error": "Human-readable error description"
}

Error Codes

HTTP Code	Meaning	When it happens	What to do
400	Bad Request	Missing or invalid parameters (e.g. missing `script`, invalid `url`, `max_videos` out of range, invalid `job_id`)	Check your request parameters against the endpoint docs
401	Unauthorized	API key is missing, invalid, or deactivated	Verify your API key is correct and active
402	Payment Required	Not enough TTS or studio credits for this request	Purchase more credits from your dashboard
403	Forbidden	Feature requires a higher plan (e.g. YouTube Scraper and Terminated Channels require Professional or Ultimate)	Upgrade your plan in Settings
404	Not Found	Resource does not exist (e.g. `job_id` not found, voice not found)	Verify the ID is correct and belongs to your account
429	Too Many Requests	You have 5 active jobs already (per-user limit)	Wait for some jobs to complete before submitting new ones
500	Server Error	Unexpected internal error	Retry the request. If persistent, contact support.

Code Examples

Complete, copy-paste examples with error handling for every API category.

Text-to-Speech

Python — TTS Generation

# pip install requests
import requests, time, sys

API_KEY = "YOUR_API_KEY"
BASE    = "https://api.algrow.online"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Submit generation
resp = requests.post(f"{BASE}/api/generate-simple", headers=HEADERS, data={
    "script":           "Welcome to our YouTube channel.",
    "voice_id":         "21m00Tcm4TlvDq8ikWAM",
    "provider":         "elevenlabs",
    "stability":        "0.7",
    "similarity_boost": "0.8",
})

data = resp.json()
if not data.get("success"):
    print(f"Error: {data.get('error')}")
    sys.exit(1)

job_id = data["job_id"]
print(f"Job submitted: {job_id}")

# 2. Poll for completion (max 60 attempts = ~3 minutes)
for attempt in range(60):
    status = requests.get(f"{BASE}/api/job-status/{job_id}", headers=HEADERS).json()

    if status["status"] == "completed":
        print(f"Audio ready: {status['audio_url']}")
        break
    elif status["status"] == "failed":
        print(f"Generation failed: {status.get('error', 'Unknown error')}")
        sys.exit(1)
    else:
        print(f"Status: {status['status']}... (attempt {attempt + 1})")
        time.sleep(3)
else:
    print("Timed out waiting for generation")
    sys.exit(1)

JavaScript (Node.js 18+)

const API_KEY = "YOUR_API_KEY";
const BASE    = "https://api.algrow.online";

async function generateTTS(text, voiceId, options = {}) {
  // 1. Submit generation
  const form = new URLSearchParams();
  form.append("script", text);
  form.append("voice_id", voiceId);
  form.append("provider", options.provider || "elevenlabs");
  if (options.stability)        form.append("stability", options.stability);
  if (options.similarity_boost) form.append("similarity_boost", options.similarity_boost);
  if (options.speed)            form.append("speed", options.speed);

  const submitRes = await fetch(`${BASE}/api/generate-simple`, {
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}` },
    body: form,
  });

  const submitData = await submitRes.json();
  if (!submitData.success) throw new Error(submitData.error);

  const jobId = submitData.job_id;
  console.log(`Job submitted: ${jobId}`);

  // 2. Poll for completion
  for (let i = 0; i < 60; i++) {
    const statusRes = await fetch(`${BASE}/api/job-status/${jobId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    const status = await statusRes.json();

    if (status.status === "completed") return status.audio_url;
    if (status.status === "failed") throw new Error(status.error || "Generation failed");

    console.log(`Status: ${status.status}... (attempt ${i + 1})`);
    await new Promise(r => setTimeout(r, 3000));
  }

  throw new Error("Timed out waiting for generation");
}

// Usage
generateTTS("Hello from the Algrow API!", "21m00Tcm4TlvDq8ikWAM", {
  stability: "0.7",
  similarity_boost: "0.8",
})
  .then(url => console.log("Audio:", url))
  .catch(err => console.error("Error:", err.message));

cURL (complete workflow)

# Step 1: Submit generation RESPONSE=$(curl -s -X POST "https://api.algrow.online/api/generate-simple" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "script=This is a complete cURL example with polling." \ -F "voice_id=21m00Tcm4TlvDq8ikWAM") echo "Submit response: $RESPONSE" JOB_ID=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])") # Step 2: Poll until complete while true; do STATUS=$(curl -s "https://api.algrow.online/api/job-status/$JOB_ID" \ -H "Authorization: Bearer YOUR_API_KEY") STATE=$(echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])") if [ "$STATE" = "completed" ]; then AUDIO=$(echo $STATUS | python3 -c "import sys,json; print(json.load(sys.stdin)['audio_url'])") echo "Audio ready: $AUDIO" break elif [ "$STATE" = "failed" ]; then echo "Failed: $STATUS" break fi echo "Status: $STATE ..." sleep 3 done

YouTube Scraper

Python — Scrape a Channel

import requests, time

API_KEY = "YOUR_API_KEY"
BASE    = "https://api.algrow.online"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. Submit scraping job
resp = requests.post(f"{BASE}/api/youtube-scraper", headers=HEADERS, json={
    "url": "https://www.youtube.com/@MrBeast",
    "video_type": "videos",
    "sort": "popular",
    "max_videos": 10,
    "include_transcripts": true,
    "include_comments": true
})

data = resp.json()
job_id = data["job_id"]
print(f"Job {job_id} queued ({data['mode']} mode)")

# 2. Poll for results
for _ in range(120):
    status = requests.get(f"{BASE}/api/youtube-scraper/{job_id}", headers=HEADERS).json()

    if status["status"] == "completed":
        result = status["result"]
        print(f"Got {result['total_videos']} videos, {result['total_views']:,} total views")
        for v in result["videos"]:
            print(f"  {v['title']} — {v['view_count']:,} views")
        break
    elif status["status"] == "failed":
        print(f"Failed: {status.get('error')}")
        break

    time.sleep(3)

cURL — Scrape a Single Video

# Scrape a single video with transcripts curl -X POST "https://api.algrow.online/api/youtube-scraper" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "include_transcripts": true}'

Terminated Channels

Python — Search Terminated Channels

import requests

API_KEY = "YOUR_API_KEY"
BASE    = "https://api.algrow.online"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Search for terminated gaming channels with 100k+ subs
resp = requests.get(f"{BASE}/api/terminated-channels/search", headers=HEADERS, params={
    "q": "gaming",
    "languages": "English",
    "min_subs": 100000,
    "sort": "subs_desc",
    "per_page": 10
})

data = resp.json()
for ch in data["channels"]:
    print(f"{ch['channel_title']} — {ch['subscriber_count']:,} subs, terminated {ch['terminated_days_ago']}d ago")
    for v in ch.get("recent_videos", []):
        print(f"  └ {v['title']} ({v['view_count']:,} views)")

cURL — Recently Terminated Channels

curl "https://api.algrow.online/api/terminated-channels/search?sort=date_desc&per_page=20" \ -H "Authorization: Bearer YOUR_API_KEY"

Studio

Python — Generate an Image

import requests, time

API_KEY = "YOUR_API_KEY"
BASE    = "https://api.algrow.online"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Submit image generation
resp = requests.post(f"{BASE}/api/generate-image", headers=HEADERS, json={
    "prompt": "a sunset over mountains, photorealistic",
    "model": "nano-banana-2",
    "aspect_ratio": "16:9"
})

job_id = resp.json()["job_id"]

# Poll for result
for _ in range(60):
    status = requests.get(f"{BASE}/api/job-status/{job_id}", headers=HEADERS).json()
    if status["status"] == "completed":
        print(f"Image: {status['result_url']}")
        break
    elif status["status"] == "failed":
        print(f"Failed: {status.get('error')}")
        break
    time.sleep(3)

cURL — Remove Captions from Video

curl -X POST "https://api.algrow.online/api/caption-remover" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"video_url": "https://example.com/my-video.mp4"}'

cURL — Generate a Video

curl -X POST "https://api.algrow.online/api/generate-video" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "a cat walking through a field of flowers", "model": "sora-2", "seconds": "5"}'

Algrow API

Quickstart

Get your API key

Submit a job

Get your audio

API Reference

How It Works

Authentication

Authorization Header (Recommended)

Query Parameter

Form Data Field

Text-to-Speech

Voice Management

Media Generation

Rate Limits

Credits & Billing

TTS Credits

Studio Credits

Error Handling

Code Examples

Text-to-Speech

YouTube Scraper

Terminated Channels

Studio

Buy More Credits