API Documentation

Complete guide to integrating with the Animagent.ai Story Animation API

Version: 1.0.0

Base URL: https://app.sumatman.ai/api

Last Updated: January 2025

Getting Started

Welcome to the Animagent.ai Story Animation API. This API allows you to programmatically create animated videos from text stories using advanced AI models.

To get started, you'll need to obtain an API key from your developer dashboard. Once you have your API key, you can begin making requests to create, manage, and retrieve your animation tasks.

The API supports multiple programming languages and provides both snake_case and camelCase parameter formats for maximum compatibility.

Obtain Your API Key

Follow these steps to get your API key:

1. Sign up at https://app.sumatman.ai
2. Navigate to the Developer section at https://app.sumatman.ai/developer
3. Generate your API key
4. Keep your API key secure and never share it publicly

Important Notes

All API requests require authentication via API key
The API currently supports one main endpoint: /api/task
Task status and management should be done through the web interface
Credits are automatically deducted when tasks are created

Authentication

Every API request must include your API key for authentication. The API supports three different methods for providing your API key, allowing you to choose the one that best fits your implementation.

Method 1: Bearer Token (Recommended)

Authorization: Bearer YOUR_API_KEY

Method 2: X-API-Key Header

X-API-Key: YOUR_API_KEY

Method 3: Request Body

{
  "api_key": "YOUR_API_KEY",
  ...other parameters
}

Example Request with Authentication

curl -X POST https://app.sumatman.ai/api/task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "story_type": "fairytale_story",
    "input_story": "A magical garden story"
  }'

Task Creation API

The main endpoint for creating animation tasks. This powerful endpoint supports four different modes of operation: create, repeat, edit, and continue.

Endpoint: POST /api/task

The API supports both snake_case and camelCase parameter formats for maximum compatibility. You can use whichever format you prefer.

Create Mode - Full Example

{
  "mode": "create",
  "story_type": "fairytale_story",
  "input_story": "Your story prompt or content here",
  "voice_language": "english",
  "illustration_style": "Japanese Ghibli-inspired Style - Studio Ghibli animation style with soft colors, detailed backgrounds, whimsical characters, and dreamlike atmosphere",
  "video_duration": 10,
  "dimension_type": "landscape",
  "narrator_name": "optional_narrator_name",
  "narrator_voice_id": "optional_voice_id",
  "audience_age": "Children",
  "audience_gender": "All",
  "audience_location": "Global",
  "temperature": 0.7,
  "search_keywords": "magic, adventure, friendship",
  "watermark_enabled": false,
  "use_fixed_character": false,
  "character_name": null,
  "enable_subtitle": true,
  "enable_zoom_effect": true,
  "enable_chapter_transitions": true,
  "copy_to_email": "user@example.com",
  "triggered_by": "api_call"
}

Alternative Structure (Wrapped in taskData)

{
  "taskData": {
    "story_type": "fairytale_story",
    "input_story": "Your story here",
    "voice_language": "english",
    "dimension_type": "landscape"
  }
}

Parameters

Parameter	Type	Required	Description
mode	string	Optional	Operation mode: create, repeat, edit, or continue (default: create)
story_type	string	Required	Type of story to generate (see Reference Data)
input_story	string	Required	The story prompt or content (minimum 10 characters)
voice_language	string	Required	Language for narration: english or chinese
dimension_type	string	Required	Video orientation: landscape or portrait
illustration_style	string	Optional	Full name of illustration style (see Reference Data)
video_duration	number	Optional	Length in minutes (3-30, default: 10)
narrator_name	string	Optional	Optional narrator name
narrator_voice_id	string	Optional	Optional specific voice ID
audience_age	string	Optional	Target audience age group
audience_gender	string	Optional	Target audience gender
audience_location	string	Optional	Target audience location
temperature	number	Optional	AI creativity level (0.0-1.0, default: 0.7)
search_keywords	string	Optional	Keywords for SEO and discovery
watermark_enabled	boolean	Optional	Enable watermark on video (default: false)
use_fixed_character	boolean	Optional	Use consistent character throughout (default: false)
character_name	string	Optional	Name of fixed character if enabled
enable_subtitle	boolean	Optional	Add subtitles to video (default: true)
enable_zoom_effect	boolean	Optional	Add zoom effects (default: true)
enable_chapter_transitions	boolean	Optional	Add chapter transitions (default: true)
copy_to_email	string	Optional	Email to send completion notification
triggered_by	string	Optional	Source of request (default: api_call)

Task Modes

The Task Creation API supports four different modes of operation, each designed for specific use cases.

Repeat Mode

Create a new version of an existing task with regenerated content

{
  "mode": "repeat",
  "task_id": "web_1755877911087_ewf2efddz",
  "triggered_by": "api_call"
}

Edit Mode

Modify a pending or processing task

{
  "mode": "edit",
  "task_id": "web_1755877911087_ewf2efddz",
  "story_type": "educational_story",
  "input_story": "Updated story content",
  "video_duration": 15,
  "triggered_by": "api_call"
}

Continue Mode

Create a continuation or sequel of a completed task

{
  "mode": "continue",
  "task_id": "web_1755877911087_ewf2efddz",
  "input_story": "Additional prompt for the continuation",
  "triggered_by": "api_call"
}

Alternative Structure with sourceTaskId

You can also use sourceTaskId instead of task_id

{
  "sourceTaskId": "web_1755877911087_ewf2efddz",
  "taskData": {
    "mode": "repeat",
    "triggered_by": "api_call"
  }
}

Important Notes

Repeat mode: All parameters from the original task are inherited
Edit mode: Cannot edit completed tasks
Continue mode: Source task must be completed
All modes support parameter overrides

Task List API

Retrieve a list of tasks for a specific user.

Endpoint: GET /api/user/:userId/tasks

Get All Tasks

curl -X GET "https://app.sumatman.ai/api/user/YOUR_USER_ID/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Completed Tasks with Pagination

curl -X GET "https://app.sumatman.ai/api/user/YOUR_USER_ID/tasks?status=completed&limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters

Parameter	Type	Required	Description
limit	number	Optional	Number of tasks to return (default: 100, max: 100)
offset	number	Optional	Number of tasks to skip for pagination (default: 0)
status	string	Optional	Filter by status: pending, processing, completed, or failed

Response Example

{
  "success": true,
  "data": {
    "tasks": [
      {
        "id": 123,
        "task_id": "web_1755877911087_ewf2efddz",
        "user_id": "your-user-id",
        "user_email": "user@example.com",
        "process_status": "completed",
        "story_type": "fairytale_story",
        "input_story": "A brave knight saves a magical kingdom",
        "video_length_minutes": 10,
        "dimension_type": "landscape",
        "voice_language": "english",
        "youtube_video_title": "The Brave Knight's Adventure",
        "youtube_video_id": "abc123",
        "youtube_video_description": "An epic tale of courage and magic...",
        "youtube_video_hashtags": "#fairytale #knight #adventure",
        "final_video_url": "https://api.sumatman.ai/videos/web_1755877911087_ewf2efddz.mp4",
        "final_image_url": "https://api.sumatman.ai/thumbnails/web_1755877911087_ewf2efddz.jpg",
        "final_share_url": "https://app.sumatman.ai/share/web_1755877911087_ewf2efddz",
        "task_created_at": "2025-08-23T10:30:00.000Z",
        "task_updated_at": "2025-08-23T10:45:00.000Z",
        "task_completed_at": "2025-08-23T10:45:00.000Z",
        "mode": "create",
        "from_task_id": null
      }
    ],
    "total": 50,
    "limit": 100,
    "offset": 0
  }
}

Task Status API

Get detailed status and information for a specific task.

Endpoint: GET /api/task/:taskId/status

Get Task Status

curl -X GET "https://app.sumatman.ai/api/task/web_1755877911087_ewf2efddz/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters

Parameter	Type	Required	Description
userId	string	Optional	User ID for security verification

Important Notes

Returns the complete task object with all fields
Includes download URLs when task is completed
Use this to poll for task completion

Task Deletion API

Delete a task that you own. Only tasks with status 'pending' or 'failed' can be deleted.

Endpoint: DELETE /api/task/:taskId

Delete a Task

curl -X DELETE https://app.sumatman.ai/api/task/web_1755877911087_ewf2efddz \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "message": "Task deleted successfully",
  "deletedTask": {
    "task_id": "web_1755877911087_ewf2efddz",
    "user_id": "your-user-id"
  }
}

Important Notes

You can only delete tasks that you own
Tasks can only be deleted if their status is 'pending' or 'failed'
Tasks with status 'processing' or 'completed' cannot be deleted
Deleting a task does not refund credits

Response Format

All API responses follow a consistent format for easy parsing and error handling.

Success Response

{
  "success": true,
  "data": {
    "taskId": "web_1755877911087_ewf2efddz",
    "creditCost": 50,
    "sceneCount": 25,
    "mode": "create",
    "status": "pending",
    "createdAt": "2025-08-23T10:30:00.000Z"
  }
}

Parameters

Parameter	Type	Required	Description
taskId	string	Required	Unique identifier for the created task
creditCost	number	Required	Number of credits deducted for this task
sceneCount	number	Required	Number of scenes that will be generated
mode	string	Required	The mode used (create/repeat/edit/continue)
status	string	Required	Current task status
createdAt	string	Required	Task creation timestamp

Error Handling

The API uses standard HTTP status codes and provides detailed error messages to help you handle errors gracefully.

Error Response Format

{
  "success": false,
  "error": "Detailed error message"
}

Invalid API Key

{
  "success": false,
  "error": "Invalid or inactive API key"
}

Missing Required Fields

{
  "success": false,
  "error": "Missing required fields: story_type and input_story"
}

Task Not Found

{
  "success": false,
  "error": "Source task not found or you do not have permission to access it"
}

Cannot Delete Processing Task

{
  "success": false,
  "error": "Cannot delete task with status 'processing'. Only tasks with status 'pending' or 'failed' can be deleted"
}

HTTP Status Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied
404	Not Found - Resource not found
500	Internal Server Error

Reference Data

Complete reference for all valid values and options supported by the API.

Story Types

Value	Label	Description
fairytale_story	🧚‍♀️ Fairytale Story	Magical tales with wonder and moral lessons
adventure_story	🗺️ Adventure Story	Exciting journeys and heroic quests
educational_story	📚 Educational Story	Learning through engaging narratives
cinematic_story	🎬 Cinematic Story	Dramatic, movie-like storytelling
sci_fi_story	🚀 Sci-Fi Story	Futuristic tales of technology and space
historical_story	🏛️ Historical Story	Stories from different time periods
romantic_story	💕 Romantic Story	Tales of love and relationships
comics_story	💥 Comics Story	Superhero and comic book adventures
bible_story	✝️ Bible Story	Religious and spiritual narratives
book_story	📖 Book Story	Classic literature adaptations
lyric_story	🎵 Lyric Story	Musical and poetic narratives
poetry_story	📝 Poetry Story	Transform poems into visual stories
fantasy_story	🐉 Fantasy Story	Epic tales of magic and mythical creatures
dream_story	💭 Dream Story	Surreal and imaginative dream narratives

Voice Languages

Value	Description
english	English narration (default)
chinese	Chinese (Mandarin) narration

Dimension Types

Value	Resolution	Aspect Ratio
landscape	1024x576 pixels	16:9 ratio
portrait	576x1024 pixels	9:16 ratio

Video Duration & Pricing

Duration	Story Length	Scene Count	Credit Cost
3 minutes	2000 chars	10 scenes	10 credits
5 minutes	3000 chars	15 scenes	30 credits
10 minutes	5000 chars	25 scenes	50 credits
15 minutes	7000 chars	32 scenes	64 credits
20 minutes	9000 chars	40 scenes	80 credits
25 minutes	11000 chars	47 scenes	94 credits
30 minutes	13000 chars	55 scenes	110 credits

Illustration Styles

Style Name	Description
Japanese Ghibli-inspired Style	Studio Ghibli animation style with soft colors, detailed backgrounds, whimsical characters, and dreamlike atmosphere
Cinematic Lighting	Professional movie-quality lighting with dramatic shadows, volumetric light rays, and high contrast cinematography
Digital Painting	Modern digital art with smooth brush strokes, rich colors, detailed textures, and professional illustration quality
Watercolor	Traditional watercolor painting with flowing colors, soft edges, transparent layers, and organic paper texture
3D Rendering	Photorealistic 3D computer graphics with realistic materials, lighting, shadows, and high-quality textures
Comic Book Style	Bold comic book illustration with strong outlines, vibrant colors, dynamic poses, and pop art aesthetics
Chinese Ink Painting	Traditional Chinese brush painting with flowing ink, minimalist composition, and elegant calligraphic strokes
Photorealistic	Ultra-realistic photography style with sharp details, natural lighting, and lifelike textures and materials
Anime Style	Japanese anime and manga illustration with large expressive eyes, stylized features, and vibrant anime colors
Oil Painting	Classical oil painting technique with rich textures, layered brushstrokes, and traditional fine art composition

Code Examples

Complete code examples in multiple programming languages to help you get started quickly.

Python - Complete Example

import requests
import json

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://app.sumatman.ai/api"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create a new task (snake_case format - recommended)
task_data = {
    "story_type": "fairytale_story",
    "input_story": "A brave knight saves a magical kingdom",
    "voice_language": "english",
    "video_duration": 10,
    "dimension_type": "landscape",
    "triggered_by": "api_call"
}

response = requests.post(f"{BASE_URL}/task", 
                         headers=headers, 
                         json=task_data)

if response.status_code == 200:
    result = response.json()
    task_id = result["data"]["taskId"]
    print(f"Task created: {task_id}")
    print(f"Credits used: {result['data']['creditCost']}")
else:
    print(f"Error: {response.json()}")

# Repeat an existing task
repeat_data = {
    "mode": "repeat",
    "task_id": task_id,
    "triggered_by": "api_call"
}

repeat_response = requests.post(f"{BASE_URL}/task",
                                headers=headers,
                                json=repeat_data)

# Alternative: Using camelCase (also supported)
task_data_camel = {
    "storyType": "fairytale_story",
    "inputStory": "A brave knight saves a magical kingdom",
    "voiceLanguage": "english",
    "videoDuration": 10,
    "dimensionType": "landscape",
    "triggeredBy": "api_call"
}

# This also works
response = requests.post(f"{BASE_URL}/task",
                         headers=headers,
                         json=task_data_camel)

JavaScript/Node.js - Complete Example

const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://app.sumatman.ai/api';

async function createTask() {
  try {
    // Create a new task
    const response = await axios.post(`${BASE_URL}/task`, {
      story_type: 'fairytale_story',
      input_story: 'A brave knight saves a magical kingdom',
      voice_language: 'english',
      video_duration: 10,
      dimension_type: 'landscape',
      triggered_by: 'api_call'
    }, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
    
    const taskId = response.data.data.taskId;
    console.log(`Task created: ${taskId}`);
    console.log(`Credits used: ${response.data.data.creditCost}`);
    
    return taskId;
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

async function continueTask(taskId) {
  try {
    // Continue an existing task
    const response = await axios.post(`${BASE_URL}/task`, {
      mode: 'continue',
      task_id: taskId,
      input_story: 'The knight discovers a hidden treasure',
      triggered_by: 'api_call'
    }, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log(`Continuation created: ${response.data.data.taskId}`);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

// Run the examples
createTask().then(taskId => {
  if (taskId) {
    // Wait for task to complete before continuing
    // Note: You need to check task status through the web interface
    // continueTask(taskId);
  }
});

cURL - Complete Examples

# Create a new task
curl -X POST https://app.sumatman.ai/api/task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "story_type": "fairytale_story",
    "input_story": "A brave knight saves a magical kingdom",
    "voice_language": "english",
    "video_duration": 10,
    "dimension_type": "landscape",
    "triggered_by": "api_call"
  }'

# Repeat an existing task
curl -X POST https://app.sumatman.ai/api/task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "repeat",
    "task_id": "web_1755877911087_ewf2efddz",
    "triggered_by": "api_call"
  }'

# Edit a pending task
curl -X POST https://app.sumatman.ai/api/task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "edit",
    "task_id": "web_1755877911087_ewf2efddz",
    "video_duration": 15,
    "triggered_by": "api_call"
  }'

# Continue a completed task
curl -X POST https://app.sumatman.ai/api/task \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "continue",
    "task_id": "web_1755877911087_ewf2efddz",
    "input_story": "The adventure continues in a new land",
    "triggered_by": "api_call"
  }'

Important Notes

Key information and best practices for using the Sumatman AI Animation API effectively.

Important Notes

Parameter Formats: Both snake_case (story_type) and camelCase (storyType) are supported
Required Fields: story_type and input_story (minimum 10 characters) are always required
Default Values: voice_language defaults to 'english', dimension_type to 'landscape', video_duration to 10 minutes
Task Management: Use the web interface at https://app.sumatman.ai for real-time status, downloads, and logs
Processing Time: Tasks typically take 5-15 minutes depending on video duration
API Key Security: Never share your API key publicly or commit it to version control
Credits System: Credits are deducted immediately upon task creation, refunded for failed tasks
Rate Limits: Maximum 10 requests per minute per API key, 100 tasks per day per account
Support: API Technical Support at support@sumatman.ai
Documentation Updates: Check this documentation regularly for updates

API Documentation

Table of Contents

Getting Started

Obtain Your API Key

Important Notes

Authentication

Method 1: Bearer Token (Recommended)

Method 2: X-API-Key Header

Method 3: Request Body

Example Request with Authentication

Task Creation API

Create Mode - Full Example

Alternative Structure (Wrapped in taskData)

Parameters

Task Modes

Repeat Mode

Edit Mode

Continue Mode

Alternative Structure with sourceTaskId

Important Notes

Task List API

Get All Tasks

Get Completed Tasks with Pagination

Parameters

Response Example

Task Status API

Get Task Status

Parameters

Important Notes

Task Deletion API

Delete a Task

Response Example

Important Notes

Response Format

Success Response

Parameters

Error Handling

Error Response Format

Invalid API Key

Missing Required Fields

Task Not Found

Cannot Delete Processing Task

HTTP Status Codes

Reference Data

Story Types

Voice Languages

Dimension Types

Video Duration & Pricing

Illustration Styles

Code Examples

Python - Complete Example

JavaScript/Node.js - Complete Example

cURL - Complete Examples

Important Notes

Important Notes