Create AI-generated videos programmatically using our Universe API. Simple, powerful, and designed for developers.
Generate an API key from your account settings
Send a POST request to create a video with your chosen universe
Poll the status endpoint until your video is ready
Generate a video using a specific universe
/api/v1/universe/{universe_slug}/create
Parameter | Type | Required | Description |
---|---|---|---|
prompt | string | Yes | The creative prompt for your video |
duration | string | No | Target Duration in seconds (e.g., "15", "30", "60", "180", "300", "600"). Default: "60" (actual duration may vary, affects cost) |
animation | boolean | No | Whether to animate the images or not. Default: true (significantly affects cost) |
language | string | No | 2-letter language code (Only for Universes with multiple languages, e.g., "en", "es", "fr") |
characters | array | No | Array of character objects or IDs |
removeWatermark | boolean | No | Request watermark removal. Default: false (only available for Creator plan) |
If you've already created characters in your account:
https://longstories.ai/characters
/characters/[character-id]
characters: [
"a4f0a51b-09b3-47b9-9aea-5c273b154a85", // Your saved character ID
"b5e1b62c-1ac4-58ca-ab5b-6d384c265b96" // Another character ID
]
Create new characters on-the-fly by providing their details:
characters: [
{
name: "Luna", // Required: Character name
description: "A wise owl", // Required: Role/personality
appearance: "Brown feathers, large golden eyes", // Optional
clothing: "A tiny wizard hat" // Optional
}
]
Create character(s) from an image via API, then reference the returned IDs in your video requests.
Endpoint: POST /api/v1/characters
(multipart form)
curl -X POST https://longstories.ai/api/v1/characters -H "x-api-key: YOUR_API_KEY" -H "Content-Type: multipart/form-data" -F "image=@/path/to/photo.jpg"
Response (example):
{
"characters": [
{
"id": "a4f0a51b-09b3-47b9-9aea-5c273b154a85",
"name": "Luna",
"description": "young explorer",
"appearance": "brown hair, green eyes",
"clothing": "blue jacket",
"characterPrompt": "Luna (young explorer, brown hair, green eyes, blue jacket)",
"imageUrl": "https://...signed-url..."
}
]
}
💡 Tip:
You can mix both approaches in the same request - use IDs for your saved characters and define new ones inline.
{
"requestId": "run_abc123xyz",
"status": "QUEUED",
"estimatedDuration": 60000,
"estimatedCredits": 150
}
Get the status of a video generation request
/api/v1/universe/status?requestId={request_id}
Polling Recommendation: Video generation typically takes 5-20 minutes depending on duration and complexity. We recommend polling the status endpoint every 30 seconds to avoid excessive API calls while staying responsive.
When Executing:
{
"status": "EXECUTING",
"isCompleted": false,
"isSuccess": false,
"output": null,
"error": null
}
When Completed Successfully:
{
"status": "COMPLETED",
"isCompleted": true,
"isSuccess": true,
"output": {
"url": "https://longstories.ai/video/abc123.mp4", // Direct MP4 video URL
"size": 15728640, // File size in bytes
"projectId": "proj_xyz789" // Project ID for reference
},
"error": null,
"creditsUsed": 147
}
When isSuccess
is true, the output.url
contains the direct URL to download your video. The video URL is publicly accessible and can be downloaded or embedded directly.
When Failed:
{
"status": "FAILED",
"isCompleted": true,
"isSuccess": false,
"output": null,
"error": {
"message": "Failed to generate video",
"details": {
"reason": "Content policy violation detected"
}
}
}
// Using fetch API
const response = await fetch('https://longstories.ai/api/v1/universe/professor-time/create', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
prompt: 'A magical adventure in an enchanted forest',
duration: '60',
animation: true,
removeWatermark: true, // Request watermark removal (Creator plan only)
characters: [
{
name: 'Luna',
description: 'A brave young explorer',
appearance: 'Long brown hair, green eyes',
clothing: 'Blue adventurer outfit'
}
]
})
});
const data = await response.json();
console.log('Request ID:', data.requestId);
// Poll for video completion (typically takes 5-20 minutes)
async function pollForCompletion(requestId, apiKey) {
const maxAttempts = 40; // 20 minutes max (40 * 30 seconds)
let attempts = 0;
while (attempts < maxAttempts) {
const response = await fetch(
`https://longstories.ai/api/v1/universe/status?requestId=${requestId}`,
{
headers: { 'x-api-key': apiKey }
}
);
const status = await response.json();
console.log(`Attempt ${attempts + 1}: ${status.status}`);
if (status.isCompleted) {
if (status.isSuccess) {
console.log('Video URL:', status.output.url);
console.log('Credits used:', status.creditsUsed);
return status;
} else {
throw new Error(status.error.message);
}
}
// Wait 30 seconds before next poll
await new Promise(resolve => setTimeout(resolve, 30000));
attempts++;
}
throw new Error('Video generation timed out');
}
How to find the universe slug for your API requests
https://longstories.ai/universes/[slug]
/universes/
If you're viewing a universe at:
https://longstories.ai/universes/professor-time
The universe slug is: professor-time
Note:
Remove watermarks from your generated videos
Important: Watermark removal must be explicitly requested using the removeWatermark: true
parameter. It is not applied automatically, even if your plan supports it.
removeWatermark: true
in your request{
"prompt": "Your creative prompt",
"duration": "60",
"animation": true,
"removeWatermark": true // ← Explicitly request watermark removal
}
Note:
API requests are limited to 100 per minute per API key. Additionally, rate limiting is handled naturally through credit consumption.
Credits are primarily determined by duration and animation:
Note: These estimates reflect what most universes use. Some universes may have higher costs due to premium models or features. Check the specific universe page for exact credit estimates before generating.
We're here to help you get started with the Universe API.
Enterprise & Custom Solutions: Need higher rate limits, dedicated support, or custom features? We offer flexible API plans for businesses and developers with specific requirements. Contact our API team to discuss your needs.
Not all plans include API access. Check our pricing page to see which plan best fits your usage needs. Not ready to commit? Reach out and we will help you test it.