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"

Image-to-Video Models

google veo-3.1-fast

image-to-video

POST /api/generations/generate

|Model: google|Version: veo-3.1-fast

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Text description for video generation (max 20,000 characters)
`auto_fix`	`boolean`	Optional	Auto-fix prompts that fail content policy
`duration`	`enum` 468	Optional	Video duration in seconds
`resolution`	`enum` 720p1080p	Optional	Output video resolution
`aspect_ratio`	`enum` 16:99:16	Optional	Video aspect ratio
`generate_audio`	`boolean`	Optional	Generate audio with video
`negative_prompt`	`string`	Optional	Content to avoid in generation

Request

{
  "model": "google",
  "model_version": "veo-3.1-fast",
  "input": {
    "prompt": "Camera slowly zooms into the scene"
  },
  "image_count": 1
}

// Available parameters:
// - prompt (required): Text description for video generation (max 20,000 characters)
// - auto_fix (optional): Auto-fix prompts that fail content policy
// - duration (optional): "4", "6", "8"
// - resolution (optional): "720p", "1080p"
// - aspect_ratio (optional): "16:9", "9:16"
// - generate_audio (optional): Generate audio with video
// - negative_prompt (optional): Content to avoid in generation

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_google_bp5vod",
  "model": "google",
  "model_version": "veo-3.1-fast",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...video.mp4"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.036Z",
  "updated_at": "2026-05-18T20:37:11.036Z"
}

// Pricing:
// Conditional pricing based on parameters

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "google",
    "model_version": "veo-3.1-fast",
    "input": {
        "prompt": "Camera slowly zooms into the scene"
    },
    "image_count": 1
}'

openai sora-2-enchanted

image-to-video

POST /api/generations/generate

|Model: openai|Version: sora-2-enchanted

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Text description for video generation
`duration`	`enum` 1015	Optional	Video duration in seconds (10s or 15s)
`n_frames`	`enum` 1015	Optional	Number of frames (10 or 15)
`image_urls`	`array`	Optional	Optional reference images (first frame, last frame)
`aspect_ratio`	`enum` landscapeportrait	Optional	Video aspect ratio - landscape or portrait
`remove_watermark`	`boolean`	Optional	Remove watermark from generated video

Request

{
  "model": "openai",
  "model_version": "sora-2-enchanted",
  "input": {
    "prompt": "Camera slowly zooms into the scene"
  },
  "image_count": 1
}

// Available parameters:
// - prompt (required): Text description for video generation
// - duration (optional): "10", "15"
// - n_frames (optional): "10", "15"
// - image_urls (optional): Optional reference images (first frame, last frame)
// - aspect_ratio (optional): "landscape", "portrait"
// - remove_watermark (optional): Remove watermark from generated video

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_openai_1s8zjp",
  "model": "openai",
  "model_version": "sora-2-enchanted",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...video.mp4"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.036Z",
  "updated_at": "2026-05-18T20:37:11.036Z"
}

// Pricing:
// Per second pricing:
// - 10: $0.1/second
// - 15: $0.1/second

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "openai",
    "model_version": "sora-2-enchanted",
    "input": {
        "prompt": "Camera slowly zooms into the scene"
    },
    "image_count": 1
}'

openai sora-2

image-to-video

POST /api/generations/generate

|Model: openai|Version: sora-2

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Text description for video generation
`seconds`	`enum` 4812	Required	Video duration in seconds
`aspect_ratio`	`enum` landscapeportrait	Required	Video aspect ratio - landscape (1280x720) or portrait (720x1280)
`input_reference`	`string`	Optional	Optional reference image

Request

{
  "model": "openai",
  "model_version": "sora-2",
  "input": {
    "prompt": "Camera slowly zooms into the scene",
    "seconds": "4",
    "aspect_ratio": "landscape"
  },
  "image_count": 1
}

// Available parameters:
// - prompt (required): Text description for video generation
// - seconds (required): "4", "8", "12"
// - aspect_ratio (required): "landscape", "portrait"
// - input_reference (optional): Optional reference image

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_openai_1s2k9j",
  "model": "openai",
  "model_version": "sora-2",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...video.mp4"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.036Z",
  "updated_at": "2026-05-18T20:37:11.036Z"
}

// Pricing:
// Per second pricing:
// - 4: $0.1/second
// - 8: $0.1/second
// - 12: $0.1/second

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "openai",
    "model_version": "sora-2",
    "input": {
        "prompt": "Camera slowly zooms into the scene",
        "seconds": "4",
        "aspect_ratio": "landscape"
    },
    "image_count": 1
}'

kwaigi kling-v2.1

image-to-video

POST /api/generations/generate

|Model: kwaigi|Version: kling-v2.1

Parameters

Parameter	Type	Required	Description
`mode`	`enum` standardpro	Optional	Generation mode quality Default: `standard`
`prompt`	`string`	Required	Text description for video generation
`duration`	`enum` 510	Optional	Video duration in seconds
`start_image`	`string`	Required	Starting image for the video (required)

Request

{
  "model": "kwaigi",
  "model_version": "kling-v2.1",
  "input": {
    "prompt": "Camera slowly zooms into the scene",
    "start_image": "data:image/png;base64,iVBORw0KGgo..."
  },
  "image_count": 1
}

// Available parameters:
// - mode (optional): "standard", "pro" (default: "standard")
// - prompt (required): Text description for video generation
// - duration (optional): "5", "10"
// - start_image (required): Starting image for the video (required)

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_kwaigi_51qrkj",
  "model": "kwaigi",
  "model_version": "kling-v2.1",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...video.mp4"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.036Z",
  "updated_at": "2026-05-18T20:37:11.036Z"
}

// Pricing:
// Per second pricing:

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "kwaigi",
    "model_version": "kling-v2.1",
    "input": {
        "prompt": "Camera slowly zooms into the scene",
        "start_image": "data:image/png;base64,iVBORw0KGgo..."
    },
    "image_count": 1
}'

minimax video-01

image-to-video

POST /api/generations/generate

|Model: minimax|Version: video-01

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Text description for video generation
`first_frame_image`	`string`	Optional	Optional starting image for the video
`subject_reference`	`string`	Optional	Optional subject reference for consistency

Request

{
  "model": "minimax",
  "model_version": "video-01",
  "input": {
    "prompt": "Camera slowly zooms into the scene"
  },
  "image_count": 1
}

// Available parameters:
// - prompt (required): Text description for video generation
// - first_frame_image (optional): Optional starting image for the video
// - subject_reference (optional): Optional subject reference for consistency

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_minimax_rdv50k",
  "model": "minimax",
  "model_version": "video-01",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...video.mp4"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.037Z",
  "updated_at": "2026-05-18T20:37:11.037Z"
}

// Pricing:
// Fixed price: $undefined per generation

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "minimax",
    "model_version": "video-01",
    "input": {
        "prompt": "Camera slowly zooms into the scene"
    },
    "image_count": 1
}'

bytedance seedance-1-pro

image-to-video

POST /api/generations/generate

|Model: bytedance|Version: seedance-1-pro

Parameters

Parameter	Type	Required	Description
`fps`	`enum` 24	Optional	Frames per second
`image`	`string`	Optional	Optional reference image
`prompt`	`string`	Required	Text description for video generation
`duration`	`enum` 510	Optional	Video duration in seconds
`resolution`	`enum` 480p1080p	Optional	Output video resolution
`aspect_ratio`	`enum` 16:94:31:13:49:1621:99:21	Optional	Video aspect ratio
`camera_fixed`	`boolean`	Optional	Whether camera position is fixed

Request

{
  "model": "bytedance",
  "model_version": "seedance-1-pro",
  "input": {
    "prompt": "Camera slowly zooms into the scene"
  },
  "image_count": 1
}

// Available parameters:
// - fps (optional): "24"
// - image (optional): Optional reference image
// - prompt (required): Text description for video generation
// - duration (optional): "5", "10"
// - resolution (optional): "480p", "1080p"
// - aspect_ratio (optional): "16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "9:21"
// - camera_fixed (optional): Whether camera position is fixed

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_bytedance_fgsfod",
  "model": "bytedance",
  "model_version": "seedance-1-pro",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...video.mp4"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.037Z",
  "updated_at": "2026-05-18T20:37:11.037Z"
}

// Pricing:
// Per second pricing:

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "bytedance",
    "model_version": "seedance-1-pro",
    "input": {
        "prompt": "Camera slowly zooms into the scene"
    },
    "image_count": 1
}'

minimax hailuo-02

image-to-video

POST /api/generations/generate

|Model: minimax|Version: hailuo-02

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Text description for video generation
`duration`	`enum` 610	Optional	Video duration in seconds
`resolution`	`enum` 512p768p1080p	Optional	Output video resolution
`first_frame_image`	`string`	Optional	Optional starting image for the video

Request

{
  "model": "minimax",
  "model_version": "hailuo-02",
  "input": {
    "prompt": "Camera slowly zooms into the scene"
  },
  "image_count": 1
}

// Available parameters:
// - prompt (required): Text description for video generation
// - duration (optional): "6", "10"
// - resolution (optional): "512p", "768p", "1080p"
// - first_frame_image (optional): Optional starting image for the video

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_minimax_uyrxk7",
  "model": "minimax",
  "model_version": "hailuo-02",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...video.mp4"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.037Z",
  "updated_at": "2026-05-18T20:37:11.037Z"
}

// Pricing:
// Conditional pricing based on parameters

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "minimax",
    "model_version": "hailuo-02",
    "input": {
        "prompt": "Camera slowly zooms into the scene"
    },
    "image_count": 1
}'

Text-to-Image Models

google nano-banana-pro

text-to-image

POST /api/generations/generate

|Model: google|Version: nano-banana-pro

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Text description for image generation (3-50,000 characters)
`num_images`	`enum` 1234	Optional	Number of images to generate
`resolution`	`enum` 1K2K4K	Optional	Output image resolution (4K charged at double rate)
`aspect_ratio`	`enum` 21:916:93:24:35:41:14:53:42:39:16	Optional	Image aspect ratio
`output_format`	`enum` jpegpngwebp	Optional	Output image format
`enable_web_search`	`boolean`	Optional	Use latest web information for generation

Request

{
  "model": "google",
  "model_version": "nano-banana-pro",
  "input": {
    "prompt": "A photorealistic landscape with mountains"
  },
  "image_count": 1
}

// Available parameters:
// - prompt (required): Text description for image generation (3-50,000 characters)
// - num_images (optional): "1", "2", "3", "4"
// - resolution (optional): "1K", "2K", "4K"
// - aspect_ratio (optional): "21:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16"
// - output_format (optional): "jpeg", "png", "webp"
// - enable_web_search (optional): Use latest web information for generation

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_google_6uwnqm",
  "model": "google",
  "model_version": "nano-banana-pro",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...image.png"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.037Z",
  "updated_at": "2026-05-18T20:37:11.037Z"
}

// Pricing:
// Conditional pricing based on parameters

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "google",
    "model_version": "nano-banana-pro",
    "input": {
        "prompt": "A photorealistic landscape"
    },
    "image_count": 1
}'

google nano-banana

text-to-image

POST /api/generations/generate

|Model: google|Version: nano-banana

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Text description for image generation
`image_input`	`array`	Optional	Optional input images

Request

{
  "model": "google",
  "model_version": "nano-banana",
  "input": {
    "prompt": "A photorealistic landscape with mountains"
  },
  "image_count": 1
}

// Available parameters:
// - prompt (required): Text description for image generation
// - image_input (optional): Optional input images

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_google_bln5r",
  "model": "google",
  "model_version": "nano-banana",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...image.png"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.037Z",
  "updated_at": "2026-05-18T20:37:11.037Z"
}

// Pricing:
// Fixed price: $undefined per generation

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "google",
    "model_version": "nano-banana",
    "input": {
        "prompt": "A photorealistic landscape"
    },
    "image_count": 1
}'

black-forest-labs flux-kontext-max

text-to-image

POST /api/generations/generate

|Model: black-forest-labs|Version: flux-kontext-max

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Text description for image generation
`input_image`	`string`	Optional	Optional input image for context
`aspect_ratio`	`enum` 1:116:99:16	Optional	Image aspect ratio Default: `match_input_image`

Request

{
  "model": "black-forest-labs",
  "model_version": "flux-kontext-max",
  "input": {
    "prompt": "A photorealistic landscape with mountains"
  },
  "image_count": 1
}

// Available parameters:
// - prompt (required): Text description for image generation
// - input_image (optional): Optional input image for context
// - aspect_ratio (optional): "1:1", "16:9", "9:16" (default: "match_input_image")

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_black-forest-labs_j6f6ng",
  "model": "black-forest-labs",
  "model_version": "flux-kontext-max",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...image.png"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.037Z",
  "updated_at": "2026-05-18T20:37:11.037Z"
}

// Pricing:
// Fixed price: $undefined per generation

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "black-forest-labs",
    "model_version": "flux-kontext-max",
    "input": {
        "prompt": "A photorealistic landscape"
    },
    "image_count": 1
}'

google imagen-4-fast

text-to-image

POST /api/generations/generate

|Model: google|Version: imagen-4-fast

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Text description for image generation
`aspect_ratio`	`enum` 4:33:416:99:161:1	Optional	Image aspect ratio

Request

{
  "model": "google",
  "model_version": "imagen-4-fast",
  "input": {
    "prompt": "A photorealistic landscape with mountains"
  },
  "image_count": 1
}

// Available parameters:
// - prompt (required): Text description for image generation
// - aspect_ratio (optional): "4:3", "3:4", "16:9", "9:16", "1:1"

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_google_ehx06p",
  "model": "google",
  "model_version": "imagen-4-fast",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...image.png"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.037Z",
  "updated_at": "2026-05-18T20:37:11.037Z"
}

// Pricing:
// Fixed price: $undefined per generation

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "google",
    "model_version": "imagen-4-fast",
    "input": {
        "prompt": "A photorealistic landscape"
    },
    "image_count": 1
}'

ideogram-ai ideogram-v3-turbo

text-to-image

POST /api/generations/generate

|Model: ideogram-ai|Version: ideogram-v3-turbo

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Required	Text description for image generation
`aspect_ratio`	`enum` 3:23:44:34:51:116:99:161:3	Optional	Image aspect ratio

Request

{
  "model": "ideogram-ai",
  "model_version": "ideogram-v3-turbo",
  "input": {
    "prompt": "A photorealistic landscape with mountains"
  },
  "image_count": 1
}

// Available parameters:
// - prompt (required): Text description for image generation
// - aspect_ratio (optional): "3:2", "3:4", "4:3", "4:5", "1:1", "16:9", "9:16", "1:3"

Response

{
  "id": 789,
  "user_id": "abc123",
  "replicate_id": "r_ideogram-ai_hv9u5",
  "model": "ideogram-ai",
  "model_version": "ideogram-v3-turbo",
  "input_parameters": {},
  "output_data": {
    "urls": [
      "https://prototipal.b-cdn.net/...image.png"
    ]
  },
  "status": "processing",
  "credits_used": "2.5",
  "created_at": "2026-05-18T20:37:11.037Z",
  "updated_at": "2026-05-18T20:37:11.037Z"
}

// Pricing:
// Fixed price: $undefined per generation

cURL Example

curl -X POST https://gateway-api.prototipal.com/api/generations/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -d '{
    "model": "ideogram-ai",
    "model_version": "ideogram-v3-turbo",
    "input": {
        "prompt": "A photorealistic landscape"
    },
    "image_count": 1
}'

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