Hugging Face's logo

Spaces:
robiul487
/
NCAkit
Sleeping

App Files Community
NCAkit / API_DOCUMENTATION.md
ismdrobiul489's picture
ismdrobiul489
docs: Add comprehensive API documentation with HF Cloud Storage section
1ccab01
preview code
|
raw
history blame contribute delete
20.7 kB

NCAKit Complete API Documentation

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

📚 Table of Contents

  1. Video Creator (Short Videos)
  2. Story Reels (AI Image Videos)
  3. Fact Image (Quote Videos)
  4. Quiz Reel (Interactive Quizzes)
  5. Text Story (Chat Story Videos)
  6. Trends (Google Trends)
  7. Common Patterns
  8. HF Cloud Storage & Download
  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:

{
  "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
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):

{
  "videoId": "abc123def456..."
}

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

Response:

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

{
  "videos": [
    {"id": "abc123", "status": "ready"},
    {"id": "def456", "status": "processing"}
  ]
}

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

Response:

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

{
  "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):

{
  "job_id": "abc123",
  "status": "queued",
  "message": "Video generation started"
}

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

Response:

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

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

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

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

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

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

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

Response:

{
  "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):

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

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

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

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

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

{
  "country": "bangladesh",
  "limit": 20
}

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

Response:

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

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

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

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

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:

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:

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

# 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 

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:

{
  "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