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)