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 | Conditional | The creative prompt for your video (required unless userScript or voiceoverKey is provided) |
| duration | string | No | Target Duration in seconds (e.g., "15", "30", "60", "180", "300", "600"). Default: "60" (actual duration may vary, affects cost) |
| animationPreset | string | No | Animation quality preset: just_storyboard, fast, pro_animation (aliases: static, pro) |
| animation | boolean | No | Legacy toggle (true = animation, false = storyboard). Ignored when animationPreset is provided |
| userScript | string | No | Provide a full script to skip script generation (cannot be used with voiceoverKey) |
| voiceoverKey | string | No | Audio file key for pre-recorded voiceover or song (cannot be used with userScript) |
| voiceoverDuration | number | No | Audio duration in seconds (requires voiceoverKey, improves timing) |
| audioKind | string | No | voiceover (default) or song (requires voiceoverKey) |
| 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 |
| visualStyleId | string (UUID) | No | Optional explicit visual style. Omit it to use the universe default behavior: AI style selection for universes with AI-style default enabled, otherwise the universe's default style. |
| preferAiStyle | boolean | No | Optional AI-style preference hint. When visualStyleId is omitted, universe default behavior still applies. To force non-AI style, provide an explicit visualStyleId. |
| removeWatermark | boolean | No | Request watermark removal. Default: false (only available for Creator plan) |
Provide userScript or voiceoverKey. For songs, set audioKind: "song".
{
"userScript": "Full script here...",
"duration": "60",
"animationPreset": "fast"
}{
"voiceoverKey": "uploads/voiceovers/my-track.mp3",
"voiceoverDuration": 42,
"audioKind": "song",
"animationPreset": "pro_animation"
}If you omit visualStyleId, the API follows the universe default: some universes default to AI style selection, while others default to the first configured style. Set visualStyleId only when you want to lock a specific look.
Note: preferAiStyle: false does not override an AI-default universe when visualStyleId is omitted. If you need non-AI style output, pass a concrete visualStyleId.
Exception: for longstories-pixel-art, omitting visualStyleIduses the universe's default pixel-art style.
{
"prompt": "A magical adventure in an enchanted forest",
"duration": "60"
// visualStyleId omitted -> universe default behavior
}{
"prompt": "A magical adventure in an enchanted forest",
"duration": "60",
"visualStyleId": "58b93c7e-edda-474b-90ef-379549964591"
}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 an estimate without starting generation
/api/v1/universe/{universe_slug}/estimateSame as the Create endpoint. Supports animationPreset, scripts, and audio inputs.
{
"estimatedDuration": 60000,
"estimatedCredits": 294
}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',
animationPreset: 'pro_animation',
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-timeThe 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",
"animationPreset": "pro_animation",
"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 preset:
Note: These estimates assume Seedream 4.5, default sound effects on, no characters, and no animation cap. Use the /estimate endpoint for accurate per‑request pricing.
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.