Skip to main content

AI API Reference

Access AI-powered features for content creation and insights using our AI API.

Base Endpoint

POST /api/v1/ai

Authentication

  • Required: Bearer token (JWT or API key)
  • Feature: Available on all plans
  • Additional Requirement: Valid Google Gemini API key configured in user settings

Endpoints

Save AI API Key

POST /api/v1/ai/api-key Save your Google Gemini API key for AI functionality.
apiKey
string
required
Your Google Gemini API key
curl -X POST 'https://api.d1g.qzz.io/api/v1/ai/api-key' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "your_gemini_api_key_here"
  }'
import axios from 'axios';

const saveAiApiKey = async () => {
  try {
    const response = await axios.post(
      'https://api.d1g.qzz.io/api/v1/ai/api-key',
      {
        apiKey: 'your_gemini_api_key_here'
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('AI API key saved successfully');
  } catch (error) {
    console.error('Failed to save AI API key:', error.response?.data || error.message);
  }
};
import requests

def save_ai_api_key():
    url = "https://api.d1g.qzz.io/api/v1/ai/api-key"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    data = {
        "apiKey": "your_gemini_api_key_here"
    }
    
    response = requests.post(url, json=data, headers=headers)
    
    if response.status_code == 200:
        print("AI API key saved successfully")
    else:
        print("Failed to save AI API key:", response.json())
{
  "success": true,
  "message": "Gemini API key saved successfully"
}

Get AI API Key Status

GET /api/v1/ai/api-key/status Check the status of your configured AI API key.
{
  "success": true,
  "data": {
    "hasApiKey": true
  }
}

Delete AI API Key

DELETE /api/v1/ai/api-key Remove your configured AI API key.
{
  "success": true,
  "message": "Gemini API key deleted successfully"
}

AI Chat

POST /api/v1/ai/chat Interact with AI for content strategy and recommendations.
message
string
required
Your message or question to the AI
conversationHistory
array
Array of previous messages for conversation context. Each message should have ‘role’ (“user” or “assistant”) and ‘content’ (string).
curl -X POST 'https://api.d1g.qzz.io/api/v1/ai/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Suggest trending topics for fitness content this week",
    "conversationHistory": [
      {"role": "user", "content": "I create fitness content"},
      {"role": "assistant", "content": "Great! I can help you with fitness content ideas."}
    ]
  }'
{
  "success": true,
  "data": {
    "response": "Based on current trends, here are some trending topics for fitness content this week:\n\n1. **Home Workout Challenges** - Short, intense home workouts are trending\n2. **Post-Workout Recovery** - Recovery techniques and stretching content\n3. **Fitness Tech Reviews** - Smart fitness equipment reviews\n4. **Seasonal Fitness Goals** - Winter fitness motivation\n5. **Mental Health & Fitness** - Connection between wellness and fitness\n\nThese topics tend to perform well for fitness creators!"
  }
}

Generate Script

POST /api/v1/ai/generate-script Generate video scripts using AI.
topic
string
required
Main topic or theme for the video
duration
integer
Target video duration in seconds (e.g., 30, 60)
tone
string
Content tone (e.g., “energetic”, “professional”, “humorous”)
curl -X POST 'https://api.d1g.qzz.io/api/v1/ai/generate-script' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "topic": "5-minute morning workout routine",
    "duration": 60,
    "tone": "energetic and motivational"
  }'
{
  "success": true,
  "data": {
    "script": "**[Hook]**\nStop hitting snooze! Transform your mornings with this 5-minute routine that'll energize your entire day!\n\n**[Main Content]**\nStart with 30 seconds of jumping jacks to get your heart pumping!\n30 seconds of high knees - bring that energy up!\n30 seconds of squats - build that lower body strength!\n30 seconds of push-ups - modify on your knees if needed!\n30 seconds of mountain climbers - core engagement time!\n30 seconds of plank hold - breathe and stay strong!\n\n**[CTA]**\nTry this every morning for a week and watch your energy levels soar! Don't forget to like and follow for more quick workouts!\n\n**[Optional Notes]**\n- Use upbeat music\n- Show each exercise clearly\n- Include countdown timer on screen\n- Hashtags: #morningworkout #quickworkout #fitness"
  }
}

AI Usage Notes

Usage Tracking:
  • AI features are available on all subscription plans
  • You need to provide your own Google Gemini API key
  • Usage costs are based on your Google Gemini API usage, not our platform limits
  • Your API key is encrypted and stored securely
AI usage costs are billed directly by Google based on your Gemini API usage. TikFlow does not charge additional fees for AI features.

Error Handling

Common AI Errors

  • 400 VALIDATION_ERROR: Invalid parameters or missing required fields
  • 403 FORBIDDEN: AI feature not available on your plan
  • 422 UNPROCESSABLE_ENTITY: Invalid or missing AI API key
  • 500 INTERNAL_ERROR: AI provider error or timeout
  • 503 SERVICE_UNAVAILABLE: AI provider temporarily unavailable

AI Provider Errors

When using Google Gemini, you may encounter provider-specific errors:
{
  "success": false,
  "error": {
    "code": "AI_PROVIDER_ERROR",
    "message": "Google Gemini API returned an error",
    "details": {
      "provider": "google_gemini",
      "errorCode": "RESOURCE_EXHAUSTED",
      "errorMessage": "Quota exceeded for this API key"
    }
  }
}
Best Practice: Always handle AI errors gracefully in your application and provide fallback content or retry mechanisms.
AI-generated content should be reviewed and verified before publishing. We are not responsible for AI-generated content accuracy, compliance, or copyright issues.