YouTube Search (via AIsa)

Search YouTube videos, channels, and playlists through AIsa's unified API. No Google API key or OAuth setup needed — just your AIsa API key.

Quick Start

# Search for videos (using requests — recommended)
python <<'EOF'
import os, json, requests
results = requests.get(
    'https://api.aisa.one/apis/v1/youtube/search',
    headers={'Authorization': f'Bearer {os.environ["AISA_API_KEY"]}'},
    params={'engine': 'youtube', 'q': 'coding tutorial'}
).json()
print(json.dumps(results, indent=2))
EOF

Base URL

https://api.aisa.one/apis/v1/youtube/search

All YouTube search requests go through this single endpoint. AIsa handles authentication with the underlying YouTube data source — you only need your AIsa API key.

Authentication

All requests require the AIsa API key in the Authorization header:

Authorization: Bearer $AISA_API_KEY

Environment Variable: Set your API key as AISA_API_KEY:

export AISA_API_KEY="YOUR_AISA_API_KEY"

Getting Your API Key

Sign in or create an account at AIsa Marketplace
Navigate to your Dashboard
Copy your API key

API Reference

YouTube Search

GET /apis/v1/youtube/search

Query Parameters

Parameter	Type	Required	Description
`engine`	string	Yes	Must be `youtube`
`q`	string	Yes	Search query (same syntax as YouTube search box)
`sp`	string	No	YouTube filter token for pagination or advanced filters
`gl`	string	No	Country code for localized results (e.g., `us`, `jp`, `gb`). Not all country codes are supported — see notes below
`hl`	string	No	Interface language (e.g., `en`, `zh`, `ja`)

Example: Basic Search

curl -s -X GET "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=machine+learning+tutorial" \
  -H "Authorization: Bearer $AISA_API_KEY"

Example: Search with Country & Language

curl -s -X GET "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=AI+news&gl=us&hl=en" \
  -H "Authorization: Bearer $AISA_API_KEY"

Example: Pagination with `sp` Token

# Use the sp token from a previous response to get the next page
curl -s -X GET "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=python+tutorial&sp=EgIQAQ%3D%3D" \
  -H "Authorization: Bearer $AISA_API_KEY"

Response

The API returns structured YouTube search results including video metadata, channel info, thumbnails, and pagination tokens.

Note: The response structure may vary by query language. English queries typically return results in the videos array. Some non-English queries may return results grouped in a sections array instead. Always check for both fields.

{
  "search_metadata": {
    "status": "Success",
    "total_time_taken": 1.2
  },
  "search_parameters": {
    "engine": "youtube",
    "q": "machine learning tutorial"
  },
  "next_page_token": "CBQQABoCEgA%3D",
  "videos": [
    {
      "position_on_page": 1,
      "title": "Machine Learning Full Course for Beginners",
      "link": "https://www.youtube.com/watch?v=abc123xyz",
      "channel": {
        "name": "Tech Academy",
        "link": "https://www.youtube.com/channel/UCxyz123",
        "thumbnail": "https://yt3.ggpht.com/..."
      },
      "published_date": "2 months ago",
      "views": 1500000,
      "length": "3:45:20",
      "description": "Complete machine learning tutorial...",
      "thumbnail": {
        "static": "https://i.ytimg.com/vi/abc123xyz/hq720.jpg",
        "rich": "https://i.ytimg.com/an_webp/abc123xyz/mqdefault_6s.webp"
      }
    }
  ]
}

Alternate response structure (non-English / some queries):

Some queries return results grouped in sections instead of a flat videos array:

{
  "sections": [
    {
      "title": "搜索结果",
      "videos": [
        {
          "title": "编程教程...",
          "link": "https://www.youtube.com/watch?v=...",
          ...
        }
      ]
    }
  ]
}

Parsing both formats:

# Handle both response structures
videos = results.get('videos', [])
if not videos and 'sections' in results:
    for section in results['sections']:
        videos.extend(section.get('videos', []))

Advanced Search Tips

YouTube's q parameter supports the same search syntax as the YouTube search box:

Search Syntax	Description	Example
Basic keywords	Standard search	`q=python tutorial`
Exact phrase	Quote for exact match	`q="machine learning basics"`
Channel filter	Search within a channel	`q=channel:GoogleDevelopers python`
Duration hint	Combine with keywords	`q=python tutorial long`

Using the `sp` Filter Token

The sp parameter accepts YouTube's encoded filter tokens. Common values:

Filter	`sp` Value	Description
Videos only	`EgIQAQ%3D%3D`	Filter to video results only
Channels only	`EgIQAg%3D%3D`	Filter to channel results only
Playlists only	`EgIQAw%3D%3D`	Filter to playlist results only
Live now	`EgJAAQ%3D%3D`	Currently live streams
This week	`EgIIAw%3D%3D`	Uploaded this week
This month	`EgIIBA%3D%3D`	Uploaded this month
Short (<4 min)	`EgIYAQ%3D%3D`	Short duration videos
Long (>20 min)	`EgIYAg%3D%3D`	Long duration videos

You can also obtain sp tokens from the next_page_token field in previous API responses for pagination.

Pagination

Use the next_page_token from a response to fetch the next page of results:

# First page
results = requests.get(
    'https://api.aisa.one/apis/v1/youtube/search',
    headers=headers,
    params={'engine': 'youtube', 'q': 'python tutorial'}
).json()

# Get next page token
next_token = results.get('next_page_token')
if next_token:
    page2 = requests.get(
        'https://api.aisa.one/apis/v1/youtube/search',
        headers=headers,
        params={'engine': 'youtube', 'q': 'python tutorial', 'sp': next_token}
    ).json()

Code Examples

JavaScript

const headers = {
  'Authorization': `Bearer ${process.env.AISA_API_KEY}`
};

// Basic YouTube search
const results = await fetch(
  'https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=AI+agents+tutorial',
  { headers }
).then(r => r.json());

console.log(results.videos);

// Search with filters
const filtered = await fetch(
  'https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=deep+learning&gl=us&hl=en&sp=EgIQAQ%3D%3D',
  { headers }
).then(r => r.json());

Python

import os
import requests

headers = {'Authorization': f'Bearer {os.environ["AISA_API_KEY"]}'}

# Basic YouTube search
results = requests.get(
    'https://api.aisa.one/apis/v1/youtube/search',
    headers=headers,
    params={'engine': 'youtube', 'q': 'AI agents tutorial'}
).json()

for video in results.get('videos', []):
    print(f"{video['title']} - {video.get('views', 'N/A')} views")

# Search with country and language
results_jp = requests.get(
    'https://api.aisa.one/apis/v1/youtube/search',
    headers=headers,
    params={'engine': 'youtube', 'q': 'プログラミング', 'gl': 'jp', 'hl': 'ja'}
).json()

Python (urllib, no dependencies)

Note: urllib may encounter 403 errors due to its default User-Agent. Using requests (above) is recommended. If you must use urllib, always set a custom User-Agent header.

import urllib.request, urllib.parse, os, json

def youtube_search(query, gl=None, hl=None, sp=None):
    """Search YouTube via AIsa API."""
    params = {'engine': 'youtube', 'q': query}
    if gl: params['gl'] = gl
    if hl: params['hl'] = hl
    if sp: params['sp'] = sp
    
    url = f'https://api.aisa.one/apis/v1/youtube/search?{urllib.parse.urlencode(params)}'
    req = urllib.request.Request(url)
    req.add_header('Authorization', f'Bearer {os.environ["AISA_API_KEY"]}')
    req.add_header('User-Agent', 'AIsa-Skill/1.0')
    return json.load(urllib.request.urlopen(req))

# Search
results = youtube_search('OpenClaw tutorial', gl='us', hl='en')

# Handle both response formats
videos = results.get('videos', [])
if not videos and 'sections' in results:
    for section in results['sections']:
        videos.extend(section.get('videos', []))

print(json.dumps(videos[:3], indent=2))

Combining with Other AIsa APIs

One of the key advantages of AIsa is the unified API key. Use the same AISA_API_KEY to combine YouTube search with other AIsa capabilities:

YouTube Search + LLM Summary

import os, requests, json

headers = {'Authorization': f'Bearer {os.environ["AISA_API_KEY"]}'}

# 1. Search YouTube
yt_results = requests.get(
    'https://api.aisa.one/apis/v1/youtube/search',
    headers=headers,
    params={'engine': 'youtube', 'q': 'latest AI developments 2026'}
).json()

# 2. Summarize with LLM (same API key!)
video_titles = [v['title'] for v in yt_results.get('videos', [])[:5]]
summary = requests.post(
    'https://api.aisa.one/v1/chat/completions',
    headers={**headers, 'Content-Type': 'application/json'},
    json={
        'model': 'qwen3-flash',
        'messages': [
            {'role': 'user', 'content': f'Summarize the trending AI topics based on these YouTube videos: {json.dumps(video_titles)}'}
        ]
    }
).json()

print(summary['choices'][0]['message']['content'])

YouTube Search + Web Search

# Search both YouTube and the web for comprehensive research
yt_results = requests.get(
    'https://api.aisa.one/apis/v1/youtube/search',
    headers=headers,
    params={'engine': 'youtube', 'q': 'AI agent frameworks 2026'}
).json()

web_results = requests.get(
    'https://api.aisa.one/apis/v1/search/smart',
    headers=headers,
    params={'q': 'AI agent frameworks 2026'}
).json()

Notes

All requests are pay-per-use through your AIsa balance — no separate YouTube API quota management
The engine parameter must always be set to youtube
Video URLs follow the format https://www.youtube.com/watch?v={videoId}
Channel URLs follow the format https://www.youtube.com/channel/{channelId}
Use next_page_token from previous responses as the sp value for pagination
The gl (country) parameter does not support all ISO country codes. Known unsupported values include cn (China). If you get Unsupported value errors, try omitting gl or use a different country code
Non-English queries may return results in a sections array instead of a flat videos array — always handle both formats
IMPORTANT: Python urllib may return 403 errors due to its default User-Agent. Use the requests library instead, or add a custom User-Agent header
IMPORTANT: When using curl commands, ensure environment variables like $AISA_API_KEY are properly expanded
IMPORTANT: When piping curl output to jq, use -s flag and ensure the API key is set

Error Handling

Status	Meaning
200	Successful search response
400	Invalid request parameters (missing `engine` or `q`)
401	Unauthorized — invalid or missing AIsa API key
429	Rate limited
500	Internal server error

Troubleshooting: API Key Issues

Check that the AISA_API_KEY environment variable is set:

echo $AISA_API_KEY

Verify the API key works with a simple test:

python <<'EOF'
import os, json, requests
try:
    result = requests.get(
        'https://api.aisa.one/apis/v1/youtube/search',
        headers={'Authorization': f'Bearer {os.environ["AISA_API_KEY"]}'},
        params={'engine': 'youtube', 'q': 'test'}
    ).json()
    videos = result.get('videos', [])
    print(f"✅ API key is valid. Results: {len(videos)} videos found")
except Exception as e:
    print(f"❌ Error: {e}")
EOF

Troubleshooting: No Results

Verify your query is not empty
Try a broader search term
If using gl, verify the country code is supported — not all ISO codes work (e.g., cn is unsupported). Try omitting gl to test
Ensure engine=youtube is included in every request
Check if results are in sections instead of videos (common for non-English queries)

youtube-search

YouTube Search (via AIsa)

Quick Start

Base URL

Authentication

Getting Your API Key

API Reference

YouTube Search

Query Parameters

Example: Basic Search

Example: Search with Country & Language

Example: Pagination with `sp` Token

Response

Advanced Search Tips

Using the `sp` Filter Token

Pagination

Code Examples

JavaScript

Python

Python (urllib, no dependencies)

Combining with Other AIsa APIs

YouTube Search + LLM Summary

YouTube Search + Web Search

Notes

Error Handling

Troubleshooting: API Key Issues

Troubleshooting: No Results

Resources

youtube-search

YouTube Search (via AIsa)

Quick Start

Base URL

Authentication

Getting Your API Key

API Reference

YouTube Search

Query Parameters

Example: Basic Search

Example: Search with Country & Language

Example: Pagination with sp Token

Response

Advanced Search Tips

Using the sp Filter Token

Pagination

Code Examples

JavaScript

Python

Python (urllib, no dependencies)

Combining with Other AIsa APIs

YouTube Search + LLM Summary

YouTube Search + Web Search

Notes

Error Handling

Troubleshooting: API Key Issues

Troubleshooting: No Results

Resources

Example: Pagination with `sp` Token

Using the `sp` Filter Token