---
name: youtube-search
description: 'YouTube Search API via AIsa unified endpoint. Search YouTube videos, channels, and playlists with a single AIsa API key — no Google API key or OAuth required. Use this skill when users want to search YouTube content. For other AIsa capabilities (LLM, financial data, Twitter, web search), see the aisa-core skill. Use when: the user needs YouTube search, trend discovery, channel research, or SERP analysis.'
compatibility: Designed for Agent Skills compatible clients such as OpenClaw, Claude Code, Hermes, and GitHub-backed skill catalogs. Requires system binaries curl, python3, environment variables AISA_API_KEY and internet access to api.aisa.one.
metadata:
  version: "1.0.1"
  aisa:
    emoji: 🎬
    requires:
      bins:
      - curl
      - python3
      env:
      - AISA_API_KEY
    primaryEnv: AISA_API_KEY
    compatibility: Designed for Agent Skills compatible clients such as OpenClaw, Claude Code, Hermes, and GitHub-backed skill catalogs. Requires system binaries curl, python3, environment variables AISA_API_KEY and internet access to api.aisa.one.
---

# YouTube Search (via AIsa)

<!-- aisa-rules:start -->
## AIsa agent rules (shared)

<!-- Generated from _shared/aisa-rules.md by scripts/sync_shared_rules.py. Do not edit this block in place. -->

These rules apply to every AIsa-backed skill and are copied from https://aisa.one/llms.txt, the single authoritative agent rule source. When this block and the rest of this skill disagree, follow this block.

### Connect (MCP first)

Pick the first option that applies. Run the command yourself; the user only approves the browser sign-in.

- **A. Your client supports remote MCP and can open a browser (default).** Add a remote MCP server named `AIsa` with URL `https://mcp.aisa.one/mcp` (Streamable HTTP), using your client's own command or config file. Auth: browser OAuth, no key needed. In a chat app (Claude, ChatGPT), the user adds it as a custom connector in settings. If you cannot add the connector yourself (sandbox, permission denied), give the user the server name and URL above and wait. Do not fall back to another method.
- **B. Your client supports remote MCP but has no browser (CI, SSH, container).** Same endpoint, with the header `Authorization: Bearer $AISA_API_KEY` set in your client's MCP config instead of browser sign-in. If `AISA_API_KEY` is not set, ask the user to create a key at https://console.aisa.one/api-keys and set it in the environment; never ask them to paste it into chat. Never print, log, or commit the key.
- **C. The client has no MCP support.** Use the CLI: `npm install -g @aisa-one/cli && aisa login` (Node.js 18+). Guide: https://aisa.one/docs/get-started/cli.md
- **D. Calling AIsa over HTTP from your own code.** LLMs, OpenAI-compatible: `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`). Data APIs: `https://api.aisa.one/apis/v1`. Auth: `Authorization: Bearer $AISA_API_KEY`. Exact paths and schemas: https://aisa.one/docs/api-reference

Direct HTTP (D) is a gated fallback, not the default. Gate (https://aisa.one/docs/get-started/cli.md#direct-http-fallback): "CLI and MCP are both unavailable, HTTP requests are supported, and a valid existing AIsa API key is already available." The curl and script examples in this skill exist for that fallback; when a connection exists, run the same operation through MCP (`search` → `batch_get_schema` → `batch_quote` → `batch_use`) or the CLI (`aisa search` → `aisa schema` → `aisa quote` → `aisa call`). Take tool names and arguments from `search` or `batch_get_schema`. Never invent them.

### Verify

Make one free authenticated call on the interface you connected:

- MCP (A, B): call `account` (no arguments). If it is not in the tool list, call `use` with `{"operation_id": "account"}` instead. Returns the key, balance, and usage.
- CLI (C): `aisa balance`. (`aisa whoami` is local only and does not count.)
- HTTP (D): `GET https://api.aisa.one/v1/models` with the Bearer header returns 200.

AIsa is connected only when this call succeeds. A tool list or a 401 response does not count.

### Spending (approval before paid calls)

- Free: docs, `GET /v1/models`, MCP `search`, `list_categories`, `batch_get_schema`, `batch_quote`, `account`, and CLI `aisa search`, `aisa schema`, `aisa quote`, `aisa balance`.
- Quote the exact calls before running them: MCP `batch_quote`, CLI `aisa quote --json`. Run only what you quoted; re-quote if the tools or arguments change. Neither `batch_use` nor `aisa call` takes a price cap.
- If the quote reports `auto_execute_eligible: true` (a small total), run it without asking, unless the user set a tighter limit or asked only for a quote.
- Otherwise, before the first such call, tell the user in one message what you plan to call, the quoted price, and a total budget for the task in USD. Wait for approval, then run calls within that budget without asking again. Ask again only if the task changes or the next call would exceed the remaining budget.
- For operations billed by rows or credits, also set the operation's own limit (for example `limit`) so the cost stays bounded.
- Do not retry a failed paid call without telling the user.
- Direct HTTP (D) follows the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback: read the endpoint's reference and published pricing first; state the exact endpoint and scope, formula or rate, and documented maximum USD exposure; then wait for a separate user message explicitly approving that scope and cap. Do not make paid calls to test availability. Docs, `/v1/models`, and capability or MCP discovery are allowed before approval.

### Cost accounting

The settled cost of a direct HTTP call is reported by the response header `X-AISA-Customer-Cost-Micros-USD` (integer micro-USD; 1 USD = 1,000,000 micro-USD), or by a successful native Tool result's `customer_cost_micros_usd`. Missing cost metadata means unknown, not free. Response bodies do not carry `usage.cost` or `usage.credits_remaining`; do not report those fields as the charge. Reference: https://aisa.one/docs/guides/pricing

### Errors

- `401`: not signed in or invalid key. Redo Connect option A (step 1A in llms.txt) or check the key.
- `402`: low balance, or the operation requires the Go-to-Market plan. The response says which and where to resolve it. Tell the user which one it is (top up the balance, or subscribe to the plan) with the link from the response; do not retry.
- `429`: rate limited. Wait and retry with backoff. Details: https://aisa.one/docs/api-reference/rate-limits
<!-- aisa-rules:end -->

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

```bash
# 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`:

```bash
export AISA_API_KEY="YOUR_AISA_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [AIsa Marketplace](https://marketplace.aisa.one)
2. Navigate to your Dashboard
3. Copy your API key

## API Reference

### YouTube Search

```bash
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

```bash
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

```bash
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

```bash
# 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.

```json
{
  "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:

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

**Parsing both formats:**

```python
# 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:

```python
# 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

```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

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

```python
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

```python
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

```python
# 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

1. Check that the `AISA_API_KEY` environment variable is set:

```bash
echo $AISA_API_KEY
```

2. Verify the API key works with a simple test:

```bash
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](https://docs.aisa.one)
- [AIsa Dashboard / Marketplace](https://marketplace.aisa.one)
- [YouTube Search API Reference](https://docs.aisa.one/reference/get_youtube-search)
- [AIsa Smart Search API](https://docs.aisa.one/reference/get_search-smart)
- [AIsa Chat Completions API](https://docs.aisa.one/reference/createchatcompletion)
- [ClawHub Skills](https://clawhub.ai)