API Documentation

Introduction

Welcome to the StoryTime Africa Developer API! This API allows you to programmatically generate videos based on story text, voice selection, background music, and story type.

The API follows REST principles and uses JSON for request and response bodies. Authentication is handled via Bearer tokens using your unique API key.

Authentication

All API requests must be authenticated using an API key provided in the `Authorization` header as a Bearer token.

You can find your API key in the Account Settings modal under the 'API' tab. The key is prefixed with `sk_`.

Authorization: Bearer sk_YOUR_USER_ID

Generate Video Endpoint

This endpoint initiates the video generation process.

Request Body Parameters

Example Request Body

{
  "story": "The wise owl shared its knowledge with the forest animals.",
  "voice": "en-NG-Ezinne",
  "music": "4",
  "storyType": "Bedtime Stories",
  "isVertical": true,
  "video_length": "medium" // Optional: Request medium length video
}

Responses

Success (202 Accepted)

Indicates the video generation process has been successfully initiated.

{
  "success": true,
  "message": "Video generation started. If connection drops, check the provided URL after ~10 minutes.",
  "videoUrl": "https://storage.googleapis.com/..." // or null if not immediately available
}

Error Responses

• 400 Bad Request: Invalid input data (e.g., missing fields, story too long). Response body includes details.
• 401 Unauthorized: Missing, invalid, or unknown API key.
• 403 Forbidden: User subscription not found or video generation limit reached.
• 500 Internal Server Error: An unexpected error occurred on the server.
• 502 Bad Gateway: Error communicating with the backend video generation service (n8n).

// Example 400 Bad Request
{
  "success": false,
  "error": "Invalid input.",
  "details": {
    "story": "Story content is required."
  }
}

// Example 403 Forbidden
{
  "success": false,
  "error": "Video generation limit reached for your current plan."
}

Code Examples

curl -X POST storytime.ericfranzee.com/api/v1/generate-video \
  -H "Authorization: Bearer sk_YOUR_USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "story": "A brave tortoise decided to race the hare...",
    "music": "1",
    "voice": "en-US-Andrew",
    "storyType": "African Folktales",
    "isVertical": false
  }'

Parameter Options

Music Options (`music`)

• 1: Joyful
• 2: Horror
• 3: Piano
• 4: Natural
• 5: Love
• others: Custom URL provided via `musicUrl`

If you select 'others', you must also provide a valid, publicly accessible URL in the musicUrl parameter.

Story Type Options (`storyType`)

• African Folktales
• History
• News
• Bedtime Stories

Voice Options (`voice`)

Choose one of the following identifiers for the desired voice: