API_DOCUMENTATION.md

# NCAKit Complete API Documentation

> **Base URL:** `https://YOUR_SPACE.hf.space` or `http://localhost:7860`

---

## 📚 Table of Contents

1. [Video Creator (Short Videos)](#1-video-creator-short-videos)
2. [Story Reels (AI Image Videos)](#2-story-reels-ai-image-videos)
3. [Fact Image (Quote Videos)](#3-fact-image-quote-videos)
4. [Quiz Reel (Interactive Quizzes)](#4-quiz-reel-interactive-quizzes)
5. [Text Story (Chat Story Videos)](#5-text-story-chat-story-videos)
6. [Trends (Google Trends)](#6-trends-google-trends)
7. [Common Patterns](#7-common-patterns)
8. [HF Cloud Storage & Download](#8-hf-cloud-storage--download)
9. [Environment Variables](#9-environment-variables)

---

## 1. Video Creator (Short Videos)

Create short-form videos with multiple scenes, background videos/images, TTS narration, and background music.

### Base Path: `/api`

---

### ▶️ POST `/api/short-video` - Create Video

Create a new short video with multiple scenes.

**Request Body:**
```json
{
  "scenes": [
    {
      "text": "Scene 1 narration text",
      "searchTerms": ["nature", "forest", "peaceful"]
    },
    {
      "text": "Scene 2 narration text",
      "searchTerms": ["city", "night", "lights"]
    }
  ],
  "config": {
    "voice": "af_heart",
    "music": "chill",
    "musicVolume": "medium",
    "captionPosition": "bottom",
    "captionBackgroundColor": "blue",
    "orientation": "portrait",
    "paddingBack": 2000
  }
}
```

**Scene Parameters:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text` | string | ✅ | Narration text (will be converted to TTS) |
| `searchTerms` | string[] | ✅ | Keywords for finding background video from Pexels/Pixabay |

**Config Parameters:**
| Field | Type | Default | Options |
|-------|------|---------|---------|
| `voice` | string | `af_heart` | See [Voice Options](#voice-options) |
| `music` | string | `null` | `sad`, `happy`, `chill`, `dark`, `hopeful`, etc. |
| `musicVolume` | string | `high` | `low`, `medium`, `high`, `muted` |
| `captionPosition` | string | `bottom` | `top`, `center`, `bottom` |
| `captionBackgroundColor` | string | `blue` | Any CSS color name |
| `orientation` | string | `portrait` | `portrait`, `landscape` |
| `paddingBack` | int | `0` | End screen duration in milliseconds |

**Response (201):**
```json
{
  "videoId": "abc123def456..."
}
```

---

### 📊 GET `/api/short-video/{video_id}/status` - Check Status

**Response:**
```json
{
  "status": "processing"
}
```

**Status Values:**
| Status | Description |
|--------|-------------|
| `processing` | Video is being generated |
| `ready` | Video is ready to download |
| `failed` | Generation failed |

---

### ⬇️ GET `/api/short-video/{video_id}` - Download Video

Returns the MP4 video file directly for download.

**Headers:**
```
Content-Type: video/mp4
Content-Disposition: attachment; filename="{video_id}.mp4"
```

---

### 📋 GET `/api/short-videos` - List All Videos

**Response:**
```json
{
  "videos": [
    {"id": "abc123", "status": "ready"},
    {"id": "def456", "status": "processing"}
  ]
}
```

---

### 🗑️ DELETE `/api/short-video/{video_id}` - Delete Video

**Response:**
```json
{"success": true}
```

---

### 🎤 GET `/api/voices` - List Available Voices

**Response:** Array of available Kokoro TTS voices.

### 🎵 GET `/api/music-tags` - List Music Moods

**Response:** Array of available background music moods.

---

## 2. Story Reels (AI Image Videos)

Create story videos with AI-generated images matching the script.

### Base Path: `/api`

---

### ▶️ POST `/api/story-reel` - Create Story Reel

**Request Body:**
```json
{
  "script": "Once upon a time, in a magical forest, a young boy discovered a hidden door...",
  "image_style": "semi-realistic",
  "voice": "af_heart"
}
```

**Parameters:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `script` | string | ✅ | Full story script text |
| `image_style` | string | ❌ | Image generation style |
| `voice` | string | ❌ | TTS voice |

**Image Styles:**
- `semi-realistic` (default)
- `anime`
- `cartoon`
- `realistic`
- `watercolor`
- `sticky animation`

**Response (201):**
```json
{
  "job_id": "abc123",
  "status": "queued",
  "message": "Video generation started"
}
```

---

### 📊 GET `/api/story-reel/{video_id}/status` - Check Status

**Response:**
```json
{
  "job_id": "abc123",
  "status": "processing",
  "progress": 45,
  "video_url": null,
  "duration": null,
  "error": null
}
```

**Status Values:**
- `queued` - Waiting in queue
- `processing` - Being generated
- `generating_audio` - TTS in progress
- `generating_images` - AI images being created
- `composing_video` - Final video composition
- `ready` - Complete
- `failed` - Error occurred

---

### ⬇️ GET `/api/story-reel/{video_id}` - Download Video

Returns MP4 file or redirects to HF Hub cloud URL.

---

### 📋 GET `/api/story-reels` - List All Story Reels

### 🗑️ DELETE `/api/story-reel/{video_id}` - Delete Story Reel

### 🎨 GET `/api/styles` - List Image Styles

### 🎤 GET `/api/voices` - List TTS Voices

---

## 3. Fact Image (Quote Videos)

Create short videos with AI-generated or stock background images and text overlays.

### Base Path: `/api/fact-image`

---

### ▶️ POST `/api/fact-image/` - Create Fact Video

**Request Body:**
```json
{
  "model": "nvidia",
  "image_prompt": "A serene mountain landscape at sunset with golden light",
  "fact_heading": "DID YOU KNOW?",
  "heading_background": {
    "enabled": true,
    "color": "rgba(255, 109, 128, 0.95)",
    "padding": 22,
    "corner_radius": 28
  },
  "fact_text": "The human brain can process images in as little as 13 milliseconds.",
  "duration": 5
}
```

**Parameters:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | ❌ | `nvidia`, `cloudflare`, `pexels` |
| `image_prompt` | string | ✅ | Background image description (10-500 chars) |
| `fact_heading` | string | ❌ | Heading text (max 50 chars) |
| `heading_background` | object | ❌ | Heading background style |
| `fact_text` | string | ✅ | Main fact text (5-200 chars) |
| `duration` | int | ❌ | Video duration 4-7 seconds |

**Heading Background Options:**
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `true` | Show/hide background |
| `color` | string | `rgba(0,0,0,0.45)` | RGBA or hex color |
| `padding` | int | `22` | Padding around text (5-50) |
| `corner_radius` | int | `28` | Border radius (0-50) |

**Response:**
```json
{
  "job_id": "abc123",
  "status": "processing",
  "status_url": "/api/fact-image/abc123/status",
  "download_url": "/api/fact-image/abc123"
}
```

---

### 📊 GET `/api/fact-image/{job_id}/status` - Check Status

**Response:**
```json
{
  "job_id": "abc123",
  "status": "generating_image",
  "progress": 30,
  "video_url": null,
  "error": null
}
```

**Status Values:**
- `queued`
- `generating_image`
- `adding_text`
- `creating_video`
- `ready`
- `failed`

---

### ⬇️ GET `/api/fact-image/{job_id}` - Download Video

### 🗑️ DELETE `/api/fact-image/{job_id}` - Delete Video

---

## 4. Quiz Reel (Interactive Quizzes)

Create quiz videos with multiple questions, TTS, and animated answers.

### Base Path: `/api/quiz`

---

### ▶️ POST `/api/quiz/generate` - Create Quiz Video

**Request Body:**
```json
{
  "quizzes": [
    {
      "hook": "GEOGRAPHY QUIZ",
      "question": "What is the highest mountain in the world?",
      "options": {
        "A": "Mount Everest",
        "B": "K2",
        "C": "Kangchenjunga"
      },
      "correct": "A",
      "explain": "Mount Everest stands at 8,848 meters"
    },
    {
      "hook": "SCIENCE QUIZ",
      "question": "What is the chemical symbol for water?",
      "options": {
        "A": "O2",
        "B": "H2O",
        "C": "CO2"
      },
      "correct": "B",
      "explain": "Water is composed of 2 hydrogen and 1 oxygen atom"
    }
  ],
  "voice": "af_heart"
}
```

**Quiz Scene Parameters:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `hook` | string | ❌ | Category label (e.g., "IQ TEST") |
| `question` | string | ✅ | The quiz question |
| `options` | object | ✅ | Must have exactly A, B, C keys |
| `correct` | string | ✅ | Correct answer: "A", "B", or "C" |
| `explain` | string | ❌ | Explanation shown after reveal |

**Response:**
```json
{
  "job_id": "abc123",
  "status": "queued",
  "message": "Quiz video generation started with 2 quizzes"
}
```

---

### 📊 GET `/api/quiz/{job_id}/status` - Check Status

**Response:**
```json
{
  "job_id": "abc123",
  "status": "processing",
  "progress": 60,
  "video_url": null,
  "error": null
}
```

---

### ⬇️ GET `/api/quiz/video/{job_id}` - Download Video

---

## 5. Text Story (Chat Story Videos)

Create fake iMessage/Messenger chat story videos with gameplay background.

### Base Path: `/api/text-story`

---

### ▶️ POST `/api/text-story/generate` - Create Text Story

**Request Body (Manual Mode):**
```json
{
  "person_a_name": "You",
  "person_b_name": "My Ex",
  "person_b_avatar": "M",
  "messages": [
    {"sender": "B", "text": "Hey... we need to talk"},
    {"sender": "A", "text": "What's up?"},
    {"sender": "B", "text": "I've been thinking about us"},
    {"sender": "B", "text": "A lot actually"},
    {"sender": "A", "text": "What do you mean?"},
    {"sender": "B", "text": "I miss you..."}
  ],
  "ending_text": "To be continued...",
  "voice_a": "af_heart",
  "voice_b": "am_fenrir"
}
```

**Parameters:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `person_a_name` | string | ❌ | Your name (right side, blue bubbles) |
| `person_b_name` | string | ❌ | Other person's name (shown in header) |
| `person_b_avatar` | string | ❌ | Avatar letter or emoji |
| `messages` | array | ✅ | Chat messages (2-50 messages) |
| `ending_text` | string | ❌ | Optional ending text overlay |
| `voice_a` | string | ❌ | Voice for Person A (default: af_heart) |
| `voice_b` | string | ❌ | Voice for Person B (default: am_fenrir) |

**Message Object:**
| Field | Type | Description |
|-------|------|-------------|
| `sender` | string | `"A"` = You (right, blue), `"B"` = Other (left, gray) |
| `text` | string | Message text (1-500 chars) |

> **Note:** The same sender CAN send multiple messages in a row for natural conversation flow!

**Response:**
```json
{
  "job_id": "abc123",
  "status": "processing",
  "message": "Started generating text story with 6 messages"
}
```

---

### 🤖 POST `/api/text-story/ai-generate` - AI Generate Conversation

Use Groq AI to generate a conversation from a prompt.

**Request Body:**
```json
{
  "prompt": "A breakup conversation where she reveals she's getting married to someone else",
  "person_a_name": "You",
  "person_b_name": "My Ex",
  "message_count": 7,
  "tone": "emotional"
}
```

**Parameters:**
| Field | Type | Default | Options |
|-------|------|---------|---------|
| `prompt` | string | - | Conversation scenario |
| `person_a_name` | string | "You" | - |
| `person_b_name` | string | "My Ex" | - |
| `message_count` | int | 7 | Approximate message count |
| `tone` | string | "emotional" | `emotional`, `funny`, `shocking`, `romantic`, `angry` |

**Response:**
```json
{
  "messages": [
    {"sender": "B", "text": "Hey..."},
    {"sender": "A", "text": "What's up?"}
  ],
  "ending_text": "To be continued..."
}
```

> **Workflow:** Use `/ai-generate` first → Get messages → Send to `/generate`

---

### 📊 GET `/api/text-story/{job_id}/status` - Check Status

**Response:**
```json
{
  "job_id": "abc123",
  "status": "processing",
  "progress": 45,
  "current_step": "Rendering chat UI...",
  "video_url": null,
  "error": null
}
```

---

### ⬇️ GET `/api/text-story/{job_id}/video` - Download Video

---

## 6. Trends (Google Trends)

Get trending topics and keyword research data.

### Base Path: `/api/trends`

---

### ▶️ POST `/api/trends/trending-now` - Get Trending Topics

**Request Body:**
```json
{
  "country": "bangladesh",
  "limit": 20
}
```

**Countries:** `united_states`, `united_kingdom`, `india`, `bangladesh`, `japan`, `germany`, `france`, `brazil`, `canada`, `australia`

**Response:**
```json
{
  "success": true,
  "count": 20,
  "trends": [
    {"rank": 1, "topic": "Cricket World Cup", "country": "bangladesh", "traffic": "100K+"},
    {"rank": 2, "topic": "BPL 2024", "country": "bangladesh", "traffic": "50K+"}
  ]
}
```

---

### 🔍 POST `/api/trends/keyword-research` - Keyword Research

**Request Body:**
```json
{
  "keyword": "weight loss",
  "region": "US",
  "timeframe": "today_12m",
  "category": "health",
  "search_type": "web"
}
```

**Parameters:**
| Field | Type | Options |
|-------|------|---------|
| `timeframe` | string | `now_1h`, `now_4h`, `now_1d`, `now_7d`, `today_1m`, `today_3m`, `today_12m`, `today_5y` |
| `category` | string | `all`, `arts_entertainment`, `health`, `sports`, etc. |
| `search_type` | string | `web`, `youtube`, `news`, `images`, `shopping` |

**Response:**
```json
{
  "success": true,
  "keyword": "weight loss",
  "region": "US",
  "timeframe": "today_12m",
  "category": "health",
  "search_type": "web",
  "related_topics": {
    "top": [{"topic": "Diet", "value": 100}],
    "rising": [{"topic": "Ozempic", "value": 5000}]
  },
  "related_queries": {
    "top": [{"query": "best diet for weight loss", "value": "100"}],
    "rising": [{"query": "semaglutide weight loss", "value": "2400%"}]
  }
}
```

---

### 📺 POST `/api/trends/youtube-trends` - YouTube Trends

**Request Body:**
```json
{
  "keyword": "coding tutorial",
  "region": "US",
  "timeframe": "today_12m"
}
```

---

### 📋 GET `/api/trends/categories` - List Categories

### 🌍 GET `/api/trends/countries` - List Countries

---

## 7. Common Patterns

### Status Polling Pattern

All video generation endpoints follow this pattern:

```
1. POST /create  →  Returns job_id
2. GET /status   →  Poll until status = "ready"
3. GET /download →  Get video file
```

**Python Example:**
```python
import requests
import time

# 1. Create video
response = requests.post(
    "https://your-space.hf.space/api/short-video",
    json={
        "scenes": [{"text": "Hello world", "searchTerms": ["nature"]}],
        "config": {"voice": "af_heart"}
    }
)
video_id = response.json()["videoId"]

# 2. Poll status
while True:
    status = requests.get(f"https://your-space.hf.space/api/short-video/{video_id}/status").json()
    if status["status"] == "ready":
        break
    elif status["status"] == "failed":
        raise Exception("Video generation failed")
    time.sleep(5)

# 3. Download video
video = requests.get(f"https://your-space.hf.space/api/short-video/{video_id}")
with open("output.mp4", "wb") as f:
    f.write(video.content)
```

---

## 8. HF Cloud Storage & Download

Videos are automatically uploaded to Hugging Face Dataset when `HF_REPO` and `HF_TOKEN` are configured. Here's how to get the download URL:

---

### 📥 Method 1: Get URL from Status Response

When video is ready, `video_url` field contains the direct cloud URL:

```python
import requests
import time

BASE_URL = "https://your-space.hf.space"
job_id = "abc123"

# Poll until ready
while True:
    response = requests.get(f"{BASE_URL}/api/story-reel/{job_id}/status")
    data = response.json()
    
    if data["status"] == "ready":
        # ✅ Cloud URL is in video_url field!
        cloud_url = data["video_url"]
        print(f"Download URL: {cloud_url}")
        # Output: https://huggingface.co/datasets/username/repo/resolve/main/story_reels/abc123.mp4?download=true
        break
    elif data["status"] == "failed":
        print(f"Error: {data.get('error')}")
        break
    
    time.sleep(3)
```

**Status Response with Cloud URL:**
```json
{
  "job_id": "abc123",
  "status": "ready",
  "progress": 100,
  "video_url": "https://huggingface.co/datasets/username/repo/resolve/main/story_reels/abc123.mp4?download=true",
  "error": null
}
```

---

### 📥 Method 2: Download Endpoint Auto-Redirect

The download endpoint automatically redirects to HF Hub URL:

```python
# Download endpoint auto-redirects to cloud
response = requests.get(
    f"{BASE_URL}/api/story-reel/{job_id}",
    allow_redirects=True  # Default
)

# Get the final URL after redirect
final_url = response.url
print(f"Final URL: {final_url}")
# Output: https://huggingface.co/datasets/...

# Or get redirect URL without following
response = requests.get(
    f"{BASE_URL}/api/story-reel/{job_id}",
    allow_redirects=False
)
if response.status_code == 302:
    cloud_url = response.headers["Location"]
```

---

### 📋 Module Support Matrix

| Module | Status Endpoint | `video_url` in Status | Auto-Redirect |
|--------|----------------|----------------------|---------------|
| Story Reels | `/api/story-reel/{id}/status` | ✅ Yes | ✅ Yes |
| Fact Image | `/api/fact-image/{id}/status` | ✅ Yes | ✅ Yes |
| Quiz Reel | `/api/quiz/{id}/status` | ✅ Yes | ✅ Yes |
| Text Story | `/api/text-story/{id}/status` | ✅ Yes | ✅ Yes |
| Video Creator | `/api/short-video/{id}/status` | ❌ No | ✅ Yes |

---

### 🔗 Cloud URL Format

```
https://huggingface.co/datasets/{HF_REPO}/resolve/main/{folder}/{video_id}.mp4?download=true
```

**Folders by Module:**
| Module | Folder |
|--------|--------|
| Video Creator | `short_video` |
| Story Reels | `story_reels` |
| Fact Image | `fact_image` |
| Quiz Reel | `quiz_reel` |
| Text Story | `text_story` |

---

### ⚡ Complete Python Example

```python
import requests
import time

def create_and_download_video(base_url, script, voice="af_heart"):
    """
    Complete workflow: Create → Poll → Get Cloud URL
    """
    
    # 1. Create video
    response = requests.post(
        f"{base_url}/api/story-reel",
        json={
            "script": script,
            "voice": voice,
            "image_style": "semi-realistic"
        }
    )
    job_id = response.json()["job_id"]
    print(f"Job created: {job_id}")
    
    # 2. Poll status until ready
    while True:
        status_resp = requests.get(f"{base_url}/api/story-reel/{job_id}/status")
        status = status_resp.json()
        
        print(f"Status: {status['status']} | Progress: {status.get('progress', 0)}%")
        
        if status["status"] == "ready":
            # 3. Get cloud URL from status response
            cloud_url = status["video_url"]
            print(f"\n✅ Video Ready!")
            print(f"Cloud URL: {cloud_url}")
            return cloud_url
            
        elif status["status"] == "failed":
            raise Exception(f"Failed: {status.get('error')}")
        
        time.sleep(5)


# Usage
cloud_url = create_and_download_video(
    base_url="https://your-space.hf.space",
    script="Once upon a time in a magical forest..."
)

# Download to file
video = requests.get(cloud_url)
with open("output.mp4", "wb") as f:
    f.write(video.content)
```

---

## 9. Environment Variables

Configure these in your HF Space secrets or `.env` file:

| Variable | Required | Description |
|----------|----------|-------------|
| `HF_TTS` | ✅ | Kokoro TTS API URL |
| `PEXELS_API` | ❌ | Pexels API key for stock videos |
| `PIXABAY_API` | ❌ | Pixabay API key for stock videos |
| `NVIDIA_API` | ❌ | NVIDIA Cosmos API key for AI images |
| `CLOUDFLARE_API` | ❌ | Cloudflare AI API key |
| `GROQ_API` | ❌ | Groq API key for AI text generation |
| `HF_REPO` | ❌ | HF Dataset repo for cloud storage |
| `HF_TOKEN` | ❌ | HF token with write access |

---

## Voice Options

### Female Voices (af_)
- `af_heart` ⭐ - Warm, engaging
- `af_bella` - Soft, natural
- `af_sarah` - Clear, professional
- `af_nova` - Energetic
- `af_sky` - Youthful

### Male Voices (am_)
- `am_adam` - Deep, authoritative
- `am_fenrir` ⭐ - Natural, conversational
- `am_michael` - Clear, professional
- `am_liam` - Friendly

### British Voices (bf_, bm_)
- `bf_emma` - British female
- `bm_george` - British male

---

## Error Handling

All endpoints return standard HTTP error codes:

| Code | Description |
|------|-------------|
| `400` | Bad request (validation error) |
| `404` | Resource not found |
| `500` | Internal server error |
| `503` | Service not initialized |

**Error Response Format:**
```json
{
  "detail": "Error message here"
}
```

---

## Interactive API Docs

FastAPI provides automatic interactive documentation:

- **Swagger UI:** `https://YOUR-SPACE.hf.space/docs`
- **ReDoc:** `https://YOUR-SPACE.hf.space/redoc`

---

*Last Updated: December 2024*