Imported from baofeng-tech/agent-skills-io (clawhub-release/youtube-search/SKILL.md). Install upstream with npx skills add baofeng-tech/agent-skills-io --skill youtube-search. Copyright stays with the author (Apache-2.0).

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

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

API Reference

YouTube Search

GET /apis/v1/youtube/search

Query Parameters

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:

Using the sp Filter Token

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

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

Troubleshooting: API Key Issues

1. Check that the AISA_API_KEY environment variable is set:

echo $AISA_API_KEY

2. 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

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

Resources

• AIsa API Documentation
• AIsa Dashboard / Marketplace
• YouTube Search API Reference
• AIsa Smart Search API
• AIsa Chat Completions API
• ClawHub Skills