Prototipal API

Documentation

Dashboard API Dashboard

API Endpoints

Build with Prototipal AI

Integrate powerful AI image and video generation into your applications with our simple REST API.

Getting Started

1Get Your API Key

API Dashboard

2Make Your First Request

Use the examples below to start generating images and videos.

API Endpoints

Video Generation Status

🎬

Get Generation Status

GET

GET /api/generations/status/{id}

|Check the status of a specific video generation using its UUID

Description

Check the status of a specific video generation using its UUID.

Authentication Required:

• A valid API key or Supabase token is needed
• The user must own the generation

Features:

• Returns the current status and progress of video generation
• Includes video output URLs if the generation is completed
• Shows error details if the video generation failed
• Note: This endpoint is specifically for video generations only

Parameters

Parameter	Type	Required	Description
`id`	`string (path)`	Required	Video generation UUID to check status for

Response

{
  "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "status": "processing",
  "output": [
    "https://prototipal.b-cdn.net/sungerbob/generations/abc123.mp4"
  ],
  "error": "string",
  "created_at": "2025-09-28T20:59:20.1122",
  "model": "openai/sora-2"
}

cURL Example

curl -X GET https://gateway-api.prototipal.com/api/generations/status/a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json"

Long Form Video

🎥

Generate Long Form Video

POST

POST /api/long-story/videos

|Create a long-form video with multiple scenes and narration

Description

Generate a long-form video with multiple scenes. Each scene can have its own prompt, and the video can include narration in multiple languages.

Features:

• Multiple scenes with individual prompts
• Automatic narration generation in multiple languages
• Support for different video styles
• Scene-based video generation

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Main topic or theme for the video
`scenes`	`array`	Required	Array of scene objects with scene_number and prompt
`language_code`	`string`	Required	Language code for narration (e.g., "en", "tr", "es")
`model`	`string`	Optional	Video model to use (default: "sora-2")
`enable_narration`	`boolean`	Optional	Enable narration (default: true)
`video_style`	`string`	Optional	Video style (e.g., "cinematic", "documentary", "auto")

Request

{
  "prompt": "A journey through space exploration",
  "model": "sora-2",
  "enable_narration": true,
  "language_code": "en",
  "scenes": [
    {
      "scene_number": 1,
      "prompt": "Astronaut floating in space"
    },
    {
      "scene_number": 2,
      "prompt": "Space station orbiting Earth"
    }
  ],
  "video_style": "cinematic"
}

Response

{
  "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "video_id": "video_abc123",
  "status": "processing",
  "message": "Video generation started"
}

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/long-story/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "prompt": "A journey through space exploration",
    "model": "sora-2",
    "enable_narration": true,
    "language_code": "en",
    "scenes": [
      {
        "scene_number": 1,
        "prompt": "Astronaut floating in space"
      },
      {
        "scene_number": 2,
        "prompt": "Space station orbiting Earth"
      }
    ],
    "video_style": "cinematic"
  }'

💰

Estimate Long Form Video Cost

POST

POST /api/long-story/videos/estimate

|Get cost estimate before generating a long-form video

Description

Get an estimate of the credits required to generate a long-form video with a specific number of scenes and model.

Parameters

Parameter	Type	Required	Description
`model`	`string`	Required	Video model to use (e.g., "sora-2")
`scene_count`	`number`	Required	Number of scenes in the video

Request

{
  "model": "sora-2",
  "scene_count": 5
}

Response

{
  "success": true,
  "model": "sora-2",
  "duration": 25,
  "scene_count_mode": true,
  "scene_info": {
    "total_scenes": 5,
    "duration_per_scene": 5,
    "scene_duration_note": "Each scene is approximately 5 seconds"
  },
  "credits": {
    "required": 125,
    "per_second": 5,
    "total": 125
  },
  "pricing": {
    "base_cost_usd_per_second": 0.05,
    "total_base_cost_usd": 1.25,
    "profit_margin": "20%"
  }
}

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/long-story/videos/estimate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "sora-2",
    "scene_count": 5
  }'

📊

Get Long Form Video Status

GET

GET /api/long-story/videos/{videoId}

|Check the status of a long-form video generation

Description

Check the status and progress of a long-form video generation using its video ID.

Parameters

Parameter	Type	Required	Description
`videoId`	`string (path)`	Required	Video ID returned from the generate endpoint

Response

{
  "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "status": "processing",
  "final_video_url": "https://prototipal.b-cdn.net/...video.mp4",
  "total_duration": 25,
  "error": null
}

cURL Example

curl -X GET https://gateway-api.prototipal.com/api/long-story/videos/video_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json"

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
402	Payment Required - Insufficient credits
404	Not Found - Resource not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong

Rate Limits

API requests are rate-limited based on your subscription plan:

• Free Plan: 10 requests per minute
• Pro Plan: 100 requests per minute
• Enterprise: Custom limits

Need Help?

Have questions?

Our support team is here to help you integrate our API successfully.

Contact Support Back to Dashboard API Dashboard