# ATechDown Video Analysis API

> Base URL: `https://www.atechdown.store/api/analyze`  
> Version: `1.0`  
> Authentication: API Key via `X-API-Key` header

---

## Authentication

Include your API key in every request:

```
X-API-Key: atd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Get your key at: https://www.atechdown.store/profile.html?tab=api

---

## Endpoint

### POST /api/analyze

Analyze a video from TikTok, Facebook, or YouTube using AI.

#### Headers

| Header | Required | Description |
|--------|----------|-------------|
| `Content-Type` | Yes | `application/json` |
| `X-API-Key` | Yes | Your API key (prefix: `atd_`) |

#### Request Body (JSON)

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `video_url` | string | **Yes** | Full URL of the video (TikTok, Facebook, YouTube) |
| `brand_info` | string | No | Brand/product context for personalized analysis |
| `mode` | string | No | `sync` (default) or `async` |
| `callback_url` | string | No | Webhook URL for async mode results |

#### Supported Platforms

| Platform | URL Pattern | Auto-detected |
|----------|-------------|---------------|
| TikTok | `tiktok.com/@user/video/...` | ✅ |
| Facebook | `facebook.com/*/videos/...` | ✅ |
| YouTube | `youtube.com/watch?v=...` | ✅ |
| YouTube Shorts | `youtube.com/shorts/...` | ✅ |
| Instagram Reels | `instagram.com/reel/...` | ✅ |

---

## Sync Mode (Default)

Send request → wait 30-60s → receive full analysis.

### Request

```json
{
  "video_url": "https://www.tiktok.com/@user/video/123456789",
  "brand_info": "Skincare cho nữ 18-35 tuổi"
}
```

### Response (200 OK)

```json
{
  "success": true,
  "analysis_id": "uuid-xxx-xxx",
  "platform": "tiktok",
  "credits_remaining": 5,
  "data": {
    "overall_score": 85,
    "viral_potential": "A",
    "layers": {
      "storytelling": {
        "hook_analysis": "...",
        "timeline_breakdown": "...",
        "improvements": ["..."]
      },
      "psychology": {
        "emotional_triggers": ["..."],
        "persuasion_techniques": ["..."],
        "viewer_retention": "..."
      },
      "audio_visual": {
        "visual_style": "...",
        "sound_analysis": "...",
        "editing_pace": "..."
      },
      "branding": {
        "cta_effectiveness": "...",
        "brand_integration": "...",
        "conversion_potential": "..."
      }
    },
    "platform_optimization": {
      "hashtags": ["..."],
      "best_posting_time": "...",
      "audience_match": "..."
    },
    "action_items": [
      "Cải thiện hook trong 3s đầu",
      "Thêm text overlay cho silent viewers",
      "Tăng CTA rõ ràng hơn"
    ]
  }
}
```

---

## Async Mode (Webhook)

Send request → receive analysis_id immediately → results sent to callback_url when done.

### Request

```json
{
  "video_url": "https://www.tiktok.com/@user/video/123456789",
  "mode": "async",
  "callback_url": "https://your-n8n.app/webhook/receive-analysis"
}
```

### Immediate Response (202 Accepted)

```json
{
  "success": true,
  "analysis_id": "uuid-xxx-xxx",
  "status": "processing",
  "message": "Analysis started. Results will be sent to callback_url when complete."
}
```

### Webhook Callback (POST to your URL)

```json
{
  "analysis_id": "uuid-xxx-xxx",
  "status": "completed",
  "data": { ... }
}
```

---

## Error Codes

| Code | Meaning | Solution |
|------|---------|----------|
| `401` | Missing or invalid API key | Check key or generate new one |
| `402` | Insufficient credits | Top up at /pricing.html |
| `429` | Rate limit exceeded (10 req/min) | Wait 60s and retry |
| `400` | Missing video_url or invalid params | Check request body |
| `500` | Internal server error | Retry after 30s |

### Error Response Format

```json
{
  "success": false,
  "message": "Description of the error",
  "docs": "https://www.atechdown.store/api"
}
```

---

## Rate Limits

- **10 requests per minute** per API key
- **1 credit deducted** per successful analysis
- Sync mode timeout: ~60 seconds

---

## Code Examples

### cURL

```bash
curl -X POST "https://www.atechdown.store/api/analyze" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: atd_your_key_here" \
  -d '{
    "video_url": "https://www.tiktok.com/@user/video/123456",
    "brand_info": "Skincare brand"
  }'
```

### Python

```python
import requests

response = requests.post(
    "https://www.atechdown.store/api/analyze",
    headers={"X-API-Key": "atd_your_key_here"},
    json={
        "video_url": "https://www.tiktok.com/@user/video/123456",
        "brand_info": "Skincare brand"
    }
)
data = response.json()
print(data["data"]["overall_score"])
```

### JavaScript

```javascript
const res = await fetch("https://www.atechdown.store/api/analyze", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "atd_your_key_here"
  },
  body: JSON.stringify({
    video_url: "https://www.tiktok.com/@user/video/123456",
    brand_info: "Skincare brand"
  })
});
const { data } = await res.json();
console.log(data.overall_score, data.layers);
```

### n8n Workflow

1. **HTTP Request Node**:
   - Method: `POST`
   - URL: `https://www.atechdown.store/api/analyze`
   - Header: `X-API-Key: atd_your_key_here`
   - Body (JSON): `{"video_url": "{{$json.video_link}}", "mode": "sync"}`

2. **For async mode**, add a Webhook Trigger node and use `callback_url` in the request.

---

## OpenAPI Schema (for AI agents)

```yaml
openapi: 3.0.0
info:
  title: ATechDown Video Analysis API
  version: "1.0"
  description: AI-powered video analysis for TikTok, Facebook, YouTube
servers:
  - url: https://www.atechdown.store
paths:
  /api/analyze:
    post:
      summary: Analyze a video
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [video_url]
              properties:
                video_url:
                  type: string
                  description: Full URL of the video
                brand_info:
                  type: string
                  description: Brand context for personalized analysis
                mode:
                  type: string
                  enum: [sync, async]
                  default: sync
                callback_url:
                  type: string
                  description: Webhook URL for async results
      responses:
        "200":
          description: Analysis complete (sync mode)
        "202":
          description: Analysis started (async mode)
        "401":
          description: Invalid API key
        "402":
          description: Insufficient credits
        "429":
          description: Rate limit exceeded
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
```

---

## Support

- Docs: https://www.atechdown.store/api
- Dashboard: https://www.atechdown.store/dashboard.html  
- API Key: https://www.atechdown.store/profile.html?tab=api
- Email: support@atechdown.store