Developer Preview

Universe API

Create AI-generated videos programmatically using our Universe API. Simple, powerful, and designed for developers.

Quick Start

1Get your API key

Generate an API key from your account settings

2Make a request

Send a POST request to create a video with your chosen universe

3Check status

Poll the status endpoint until your video is ready

API Endpoints

Create Video

Generate a video using a specific universe

POST
/api/v1/universe/{universe_slug}/create

Request Body

ParameterTypeRequiredDescription
promptstringYesThe creative prompt for your video
durationstringNoTarget Duration in seconds (e.g., "15", "30", "60", "180", "300", "600"). Default: "60" (actual duration may vary, affects cost)
animationbooleanNoWhether to animate the images or not. Default: true (significantly affects cost)
languagestringNo2-letter language code (Only for Universes with multiple languages, e.g., "en", "es", "fr")
charactersarrayNoArray of character objects or IDs
removeWatermarkbooleanNoRequest watermark removal. Default: false (only available for Creator plan)

Using Characters - Three Options

Option 1: Use Existing Character IDs

If you've already created characters in your account:

  1. Go to your characters page: https://longstories.ai/characters
  2. Click on a character to view its details
  3. The character ID is in the URL: /characters/[character-id]
characters: [
  "a4f0a51b-09b3-47b9-9aea-5c273b154a85",  // Your saved character ID
  "b5e1b62c-1ac4-58ca-ab5b-6d384c265b96"   // Another character ID
]
Option 2: Define Characters Inline

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
  }
]
Option 3: Upload Image → Create Characters

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.

Response

{
  "requestId": "run_abc123xyz",
  "status": "QUEUED",
  "estimatedDuration": 60000,
  "estimatedCredits": 150
}

Check Status

Get the status of a video generation request

GET
/api/v1/universe/status?requestId={request_id}

Response Examples

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"
    }
  }
}

Status Values

QUEUEDEXECUTINGCOMPLETEDFAILEDCANCELEDTIMED_OUT

Code Examples

Create Video with Characters

// 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);

Check Status

// 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');
}

Finding Universe Slugs

How to find the universe slug for your API requests

Getting a Universe Slug

  1. Browse to any universe on LongStories.ai
  2. Look at the URL: https://longstories.ai/universes/[slug]
  3. The slug is the part after /universes/
Example:

If you're viewing a universe at:

https://longstories.ai/universes/professor-time

The universe slug is: professor-time

Note:

  • Only public universes or universes you created can be accessed via API
  • Universe slugs are case-sensitive
  • Some universes may have restricted API access

Watermark Removal

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.

Requirements

  • A plan that supports watermark removal
  • Must include removeWatermark: true in your request
  • Applies to all video durations and animation settings

Example Usage

{
  "prompt": "Your creative prompt",
  "duration": "60",
  "animation": true,
  "removeWatermark": true  // ← Explicitly request watermark removal
}

Note:

  • If you don't include this parameter, videos will have watermarks regardless of your plan
  • If you request watermark removal without the plan that supports it, the request will still succeed but watermarks will remain

Limits

Max duration600s (10 min)
Rate limit100 req/min

API requests are limited to 100 per minute per API key. Additionally, rate limiting is handled naturally through credit consumption.

Credit Usage

Credits are primarily determined by duration and animation:

Without Animation (1 min)~23 credits
Without Animation (3 min)~69 credits
Without Animation (10 min)~230 credits
With Animation (1 min)~383 credits
With Animation (3 min)~1,149 credits
With Animation (10 min)~3,830 credits

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.

Need Help?

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.