302ai-api-integration

# 302.AI API Integration Assistant

Quickly help users find and integrate any of 302.AI's 1400+ APIs into their code.

## Description

This is a specialized assistant for 302.AI API integration. When users need AI capabilities in their projects, this Skill will:

1. Automatically search 302.AI's API list to find the most suitable API
2. Retrieve detailed API documentation and usage instructions
3. Generate integration code based on user's programming language
4. Configure code with user's API Key

## Trigger Conditions

**IMPORTANT: Use this skill proactively whenever user mentions:**

- Any AI functionality (LLM, image generation, video generation, audio processing, etc.)
- Specific AI models (GPT-4, Claude, DALL-E, Stable Diffusion, etc.)
- API needs or integration requirements
- 302.AI or any AI service
- Text processing, image editing, video creation, speech recognition, etc.

## Workflow

### Step 1: Get API Key

Before starting, must obtain user's 302.AI API Key:

```
To help you integrate 302.AI APIs, I need your API Key.

Please provide your 302.AI API Key (unified for all APIs):
```

**Important**:
- All 302.AI APIs use a unified API Key
- Must ask if user hasn't provided it
- API Key format usually starts with `sk-`

### Step 2: Understand User Requirements

Analyze what functionality user wants to implement and determine which API category is needed. Reference API categories:

#### 1. Language Models (LLM)
- Chat, text generation, code generation, translation, summarization, etc.
- Includes: OpenAI, Claude, Gemini, Chinese models, etc.

#### 2. Image Generation
- Text-to-image, image-to-image, AI painting, etc.
- Includes: DALL-E, Midjourney, Stable Diffusion, Flux, etc.

#### 3. Image Processing
- Image editing, background removal, super-resolution, style transfer, 3D generation, etc.
- Includes: Basic features, advanced features, ComfyUI workflows

#### 4. Video Generation
- Text-to-video, image-to-video, digital humans, etc.
- Includes: Runway, Pika, Luma AI, Kling, etc.

#### 5. Audio/Video Processing
- TTS (text-to-speech), STT (speech-to-text), music generation, audio processing

#### 6. Information Processing
- Search services, document processing, web scraping, social media, code execution

#### 7. RAG Related
- Embeddings, Rerank, knowledge base

#### 8. Tool APIs
- Creative tools, writing tools, professional tools

#### 9. Management Functions
- Account management, usage statistics

### Step 3: Search APIs

**⚠️ CRITICAL: Use the parse script, DO NOT read llms.txt directly**

To reduce context usage, **MUST** use the `scripts/parse_api_list.py` script via Bash:

**Bash Command Usage:**

```bash
# Search by keyword
python3 scripts/parse_api_list.py "keyword"

# Search by keyword and category
python3 scripts/parse_api_list.py "keyword" "category"

# Examples:
python3 scripts/parse_api_list.py "GPT"
python3 scripts/parse_api_list.py "image generation"
python3 scripts/parse_api_list.py "chat" "language model"
python3 scripts/parse_api_list.py "nano-banana"
```

**Python Module Usage (if needed):**

```python
from scripts.parse_api_list import fetch_llms_txt, parse_llms_txt, search_apis, extract_doc_id

# Auto-fetch latest API list
content = fetch_llms_txt()

# Parse API list
apis = parse_llms_txt(content)

# Search based on user needs (supports keyword and category filtering)
results = search_apis(apis, keyword='user_keyword', category='category')

# Display results for user selection
for i, api in enumerate(results, 1):
    print(f"{i}. {api['name']}")
    print(f"   Category: {api['category']}")
    print(f"   Description: {api['description']}")
    print(f"   Docs: {api['link']}")
```

**⚠️ CRITICAL RULES (MUST FOLLOW)**:
- **ALWAYS use the script to search APIs, don't be lazy!**
- **FORBIDDEN to use WebFetch to directly read llms.txt**, this wastes massive context
- Script automatically fetches the latest API list
- **Note**: `/v1/models` endpoint only lists LLM language models, NOT image/video/audio models
- **If user needs image generation, video generation, audio processing, etc., MUST use script to search llms.txt for corresponding APIs**

For detailed usage, refer to `references/parse_script_usage.md`.

### Step 4: Search and Filter APIs

Based on user needs and Step 2 categories, search for matching APIs in the API list:

1. **Filter by category**: First locate the major category and subcategory
2. **Keyword matching**: Search for relevant keywords in descriptions
3. **Model matching**: If user specifies a specific model (like GPT-4), match directly

### Step 5: Display Candidate APIs

Show found APIs to user for selection:

```
I found the following available APIs:

1. **OpenAI Chat**
   - Category: Language Models > OpenAI
   - Description: Supports GPT-4, GPT-3.5 and other chat models
   - Docs: https://doc.302.ai/147522039e0.md

2. **Claude Chat**
   - Category: Language Models > Claude
   - Description: Supports Claude 3.5 Sonnet, Claude 3 Opus and other models
   - Docs: https://doc.302.ai/xxxxxxxxx.md

Please select the API you want to use (enter number):
```

### Step 6: Get Detailed Documentation

After user selection, use WebFetch to get detailed API documentation:

```
WebFetch(
    url="[user_selected_api_doc_link]",
    prompt="Extract API endpoint, request parameters, response format, usage examples and other detailed information"
)
```

### Step 7: Generate Integration Code

Generate complete integration code based on:

1. **User's programming language** (ask user or infer from context)
2. **API detailed documentation** (from Step 6)
3. **User's API Key** (from Step 1)
4. **User's specific requirements** (e.g., parameter configuration, feature customization)

Reference code templates in `references/integration_examples.md`, generate code including:

- Complete API call function
- Correct endpoint URL
- Required request headers (including API Key)
- Request parameter examples
- Error handling
- Usage examples

**Supported Programming Languages**:
- Python
- JavaScript/Node.js
- TypeScript
- Go
- cURL commands
- Others (based on user needs)

### Step 8: Code Explanation and Optimization Suggestions

After generating code, provide:

1. **Code explanation**: Explain key parts
2. **Parameter explanation**: List configurable parameters and their meanings
3. **Usage examples**: Show how to call the generated functions
4. **Important notes**:
   - API Key security (recommend using environment variables)
   - Rate limits
   - Error handling
   - Timeout settings
5. **Optimization suggestions**: Provide performance optimization suggestions based on user scenario

## Code Generation Standards

### Python Code Standard

```python
import requests
import json

# 302.AI API Configuration
API_KEY = "{user_API_KEY}"
BASE_URL = "https://api.302.ai"

def call_api(endpoint, data):
    """
    Call 302.AI API

    Args:
        endpoint: API endpoint
        data: Request data

    Returns:
        API response result
    """
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }

    url = f"{BASE_URL}{endpoint}"

    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"API call failed: {e}")
        return None

# Usage example
if __name__ == "__main__":
    result = call_api("/v1/chat/completions", {
        "model": "gpt-4",
        "messages": [
            {"role": "user", "content": "Hello!"}
        ]
    })

    if result:
        print(json.dumps(result, indent=2, ensure_ascii=False))
```

### JavaScript Code Standard

```javascript
const axios = require('axios');

// 302.AI API Configuration
const API_KEY = '{user_API_KEY}';
const BASE_URL = 'https://api.302.ai';

async function callAPI(endpoint, data) {
    try {
        const response = await axios.post(`${BASE_URL}${endpoint}`, data, {
            headers: {
                'Authorization': `Bearer ${API_KEY}`,
                'Content-Type': 'application/json'
            }
        });
        return response.data;
    } catch (error) {
        console.error('API call failed:', error.message);
        return null;
    }
}

// Usage example
(async () => {
    const result = await callAPI('/v1/chat/completions', {
        model: 'gpt-4',
        messages: [
            { role: 'user', content: 'Hello!' }
        ]
    });

    if (result) {
        console.log(JSON.stringify(result, null, 2));
    }
})();
```

## Advanced Features

### Streaming Response Handling

For APIs supporting streaming responses (like chat models), generate streaming code:

**Python Streaming Example**:
```python
def call_api_stream(endpoint, data):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }

    url = f"{BASE_URL}{endpoint}"

    response = requests.post(url, headers=headers, json=data, stream=True)

    for line in response.iter_lines():
        if line:
            line = line.decode('utf-8')
            if line.startswith('data: '):
                data = line[6:]
                if data != '[DONE]':
                    yield json.loads(data)
```

### Batch Processing

For scenarios requiring batch calls, provide batch processing code:

```python
def batch_call_api(endpoint, data_list):
    results = []
    for data in data_list:
        result = call_api(endpoint, data)
        if result:
            results.append(result)
    return results
```

### Async Processing

For high-concurrency scenarios, provide async processing code:

**Python Async Example**:
```python
import asyncio
import aiohttp

async def call_api_async(session, endpoint, data):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }

    url = f"{BASE_URL}{endpoint}"

    async with session.post(url, headers=headers, json=data) as response:
        return await response.json()

async def batch_call_async(endpoint, data_list):
    async with aiohttp.ClientSession() as session:
        tasks = [call_api_async(session, endpoint, data) for data in data_list]
        return await asyncio.gather(*tasks)
```

## Common Issues

### 1. Invalid API Key

```
If you encounter "Invalid API Key" error:
1. Check if API Key is correctly copied (watch for spaces)
2. Confirm API Key is activated
3. Check if API Key has sufficient quota
4. Visit 302.AI console to confirm Key status
```

### 2. Rate Limiting

```
If you encounter "Rate Limit Exceeded" error:
1. Add request intervals (time.sleep() or setTimeout())
2. Implement exponential backoff retry mechanism
3. Consider upgrading API plan
4. Use batch interfaces to reduce request count
```

### 3. Timeout Errors

```
If you encounter timeout errors:
1. Increase request timeout duration
2. Check network connection
3. For large file processing, consider using async interfaces
4. Implement retry mechanism
```

## Reference Resources

- **API Category Index**: `references/api_categories.md`
- **Integration Code Templates**: `references/integration_examples.md`
- **Official Documentation**: https://doc.302.ai/
- **API List**: https://doc.302.ai/llms.txt

## Usage Examples

### Example 1: Integrate GPT-4 Chat

**User**: "I want to use GPT-4 in my Python project"

**Assistant**:
1. Ask for API Key
2. Get latest API list
3. Find OpenAI Chat API
4. Get detailed documentation
5. Generate Python integration code
6. Provide usage instructions and optimization suggestions

### Example 2: Integrate Image Generation

**User**: "I need to call DALL-E to generate images in Node.js"

**Assistant**:
1. Ask for API Key
2. Get latest API list
3. Find DALL-E API in image generation category
4. Get detailed documentation
5. Generate JavaScript integration code
6. Provide image download and save example code

### Example 3: Integrate Speech-to-Text

**User**: "How to use 302.AI's speech recognition API?"

**Assistant**:
1. Ask for API Key and programming language
2. Get latest API list
3. Find speech recognition API in Audio/Video Processing > STT category
4. Get detailed documentation
5. Generate integration code in corresponding language
6. Provide complete example for audio file upload and processing

## Important Notes

1. **API Key Security**:
   - Never hardcode API Key in public code
   - Recommend using environment variables or config files
   - Ignore files containing API Key in version control
   - **⚠️ CRITICAL WARNING**: For pure frontend web pages (HTML/JavaScript), API Key will be exposed in client code, posing leak risk
   - **RECOMMENDED SOLUTION**: Use backend frameworks like Next.js, Express, Flask to call APIs on server side, frontend accesses indirectly through backend endpoints

2. **Error Handling**:
   - Always include comprehensive error handling logic
   - Log errors for debugging
   - User-friendly error messages

3. **Performance Optimization**:
   - For high-frequency calls, consider using connection pools
   - Implement request caching to reduce duplicate calls
   - Use async processing to improve concurrency performance

4. **Cost Control**:
   - Monitor API call volume
   - Set call limits
   - Optimize prompts to reduce token consumption

5. **Documentation Updates**:
   - API list is updated regularly
   - Re-fetch latest list before each use
   - Follow 302.AI official announcements