ScaleValue Logo
ScaleValue

🔌 Kahani Magic APIs

18 API routes documentation
Last Updated: January 21, 2026

API Overview

| Category | Routes | Purpose | |----------|--------|---------| | Story | 2 | Generate and regenerate stories | | Image | 1 | Image generation | | Audio | 4 | TTS, analysis, alignment, cues | | Animation | 2 | Kinetic and phrases | | Video | 2 | Planning and generation | | Other | 7 | Translation, profile, etc. |

Generation APIs

POST /api/kahani-magic/generate-story

Generates complete story from prompt or PDF.

// Request
{
  prompt: string;
  file?: { base64: string; mimeType: string };
  pageCount: number;               // 3-50
  targetLanguage: string;          // "hi-en", "en", etc.
  narrativeMode?: NarrativeMode;   // "direct", "cinematic", etc.
  preset: {
    audienceId: string;
    styleId: string;
    imageStyleId?: string;
    voiceStyleId?: string;
    writingStyleId?: string;
  };
  profile?: {
    protagonistName: string;
    characterAppearance?: string;
  };
}

// Response
{
  story: Story;  // Full story object with pages
}

Used By: page.tsx → InputForm → handleGenerateStory

POST /api/kahani-magic/regenerate-text

Regenerates text for a single page.

// Request
{
  currentText: string;
  pageNumber: number;
  storyContext: string;
  styleId: string;
  languageCode: string;
}

// Response
{
  text: string;
  imagePrompt: string;
}

POST /api/kahani-magic/generate-image

Generates illustration for a page.

// Request
{
  text: string;              // Page text
  imagePrompt: string;       // Visual description
  imageStyleId?: string;     // Style preset
  characterAppearance?: string;
  faceReferenceUrl?: string; // For consistency
}

// Response
{
  imageBase64: string;
  imageUrl?: string;         // If auto-uploaded
}

Rate Limited: Yes (Imagen 3)

POST /api/kahani-magic/generate-audio

Generates TTS audio for narration.

// Request
{
  text: string;
  voiceStyleId?: string;       // Voice preset
  languageCode: string;        // Critical for Hindi
  enableEmotionalExpression?: boolean;
}

// Response
{
  audio: string;               // Base64
  duration: number;            // Seconds
  wordTimings?: WordTiming[];  // If provider supports
}

Provider Chain: Gemini TTS → ElevenLabs

POST /api/kahani-magic/analyze-audio

Transcribes audio for word timings.

// Request
{
  audioBase64: string;
  languageCode: string;
}

// Response
{
  transcription: string;
  wordTimings: WordTiming[];
}

Provider: Deepgram Nova

POST /api/kahani-magic/align-text

Aligns text with audio for highlighting.

// Request
{
  text: string;
  audioDuration: number;
}

// Response
{
  wordTimings: WordTiming[];
}

⚠️ Issue: Currently heuristic-based (divides evenly)

POST /api/kahani-magic/generate-audio-cues

Generates BGM, ambient, and SFX cues.

// Request
{
  text: string;
  styleId: string;
  pageNumber: number;
}

// Response
{
  bgmMood: BGMMood;
  ambientScene: AmbientScene;
  sfxTriggers: SFXTriggerCue[];
}

Animation APIs

POST /api/kahani-magic/analyze-phrases

Analyzes text for caption typography.

// Request
{
  text: string;
  styleId?: string;
  audioDuration?: number;
  // languageCode MISSING - issue!
}

// Response
{
  phrases: PhraseAnalysis[];
}

⚠️ Issue: languageCode not passed

POST /api/kahani-magic/generate-kinetic

Generates word-level animation effects.

// Request
{
  text: string;
  styleId?: string;
  languageCode?: string;
}

// Response
{
  animations: WordAnimation[];
}

⚠️ Issue: Array length may not match word count

Video APIs

POST /api/kahani-magic/plan-segments

Plans video segment structure.

// Request
{
  text: string;
  imagePrompt: string;
  pageNumber: number;
}

// Response
{
  segments: VideoSegment[];
}

POST /api/kahani-magic/generate-segment

Generates single video segment.

// Request
{
  prompt: string;
  duration: number;
  imageStyleId?: string;
}

// Response
{
  videoBase64: string;
  duration: number;
}

Provider: Veo 2

Profile APIs

POST /api/kahani-magic/analyze-voice

Analyzes voice sample for matching.

// Request
{
  audioBase64: string;
}

// Response
{
  analysis: VoiceAnalysis;
  matchedVoiceId: string;
  customPrompt: string;
}

POST /api/kahani-magic/analyze-photo

Analyzes photo for character appearance.

// Request
{
  imageBase64: string;
}

// Response
{
  appearance: AppearanceDescription;
}

POST /api/kahani-magic/character-sheet

Generates character reference sheet.

// Request
{
  appearance: AppearanceDescription;
  style?: string;
}

// Response
{
  sheetBase64: string;
  sheetUrl?: string;
}

Translation APIs

POST /api/kahani-magic/translate

Translates text with optional transliteration.

// Request
{
  text: string;
  targetLanguage: string;
  transliterate?: boolean;  // Roman script output
}

// Response
{
  translatedText: string;
}

API Issues Summary

| API | Issue | Priority | |-----|-------|----------| | /generate-audio | No timestamps | 🔴 Critical | | /align-text | Heuristic only | 🔴 Critical | | /analyze-phrases | No languageCode | 🔴 Critical | | /generate-kinetic | Array mismatch | 🔴 Critical |

API Authentication

All APIs use Clerk session authentication:

import { auth } from '@clerk/nextjs';

export async function POST(request: Request) {
  const { userId } = auth();
  if (!userId) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  // ...
}

Credit Costs

| API | Credits | |-----|---------| | /generate-story | 0 (free) | | /generate-image | 1 per image | | /generate-audio | 0 (free) | | /generate-segment | 2 per segment |

See ../API_REFERENCE.md for full platform API docs