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"
# 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.
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)
Resources