GenFire Public API

Full API Reference

Use GenFire as a production content engine for images, videos, speech, music, sound effects, lip-sync, product extraction, workflow automation, and webhook-driven orchestration.

Base URL

/v1

https://api.genfire.ai/v1

Auth

Bearer

API key or OAuth access token

Async Pattern

Runs

Poll GET /runs/{'{runId}'} for progress

Machine Contract

OpenAPI 3.1

Download the JSON contract

Common Conventions

Send Authorization: Bearer ... on every protected endpoint.
Send Idempotency-Key on mutating generation, workflow, batch, and product extraction endpoints that require it.
Most long-running operations return a run resource immediately and finish asynchronously.
Errors follow one JSON shape. Example:

{
  "type": "https://api.genfire.ai/errors/invalid_prompt",
  "title": "Invalid Prompt",
  "status": 400,
  "detail": "prompt is required.",
  "code": "invalid_prompt",
  "request_id": "req_123"
}

Discovery

Public Model Aliases

Always use these aliases in API requests. Do not send internal provider model ids.

image_generation

GenFire v1

image.genfire_v1

GenFire's signature image model — tuned for ad/product creative.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16",
    "4:3",
    "3:4"
  ],
  "max_count": 4
}

image_generation

Nano Banana 2

image.nano_banana_2 default

Google's general-purpose image model. Fast, broad subject coverage. Default.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16",
    "4:3",
    "3:4",
    "21:9",
    "9:21"
  ],
  "max_count": 4
}

image_generation

Nano Banana Pro

image.nano_banana_pro

Premium photoreal image generation, higher fidelity than Nano Banana 2.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16",
    "4:3",
    "3:4"
  ],
  "max_count": 4
}

image_generation

Nano Banana

image.nano_banana

Standard speed and quality. Cheaper than Pro for high-volume use.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16",
    "4:3",
    "3:4"
  ],
  "max_count": 4
}

image_generation

Nano Banana Lite

image.nano_banana_lite

Gemini 3.1 Flash Lite Image — ultra-low latency, cheapest tier. Supports editing.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16",
    "4:3",
    "3:4",
    "21:9",
    "9:21"
  ],
  "max_count": 4
}

image_generation

Nano Banana 2 Lite

image.nano_banana_2_lite

Gemini 3.1 Flash Lite Image (v2) — ultra-low latency text-to-image. No edit endpoint.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16",
    "4:3",
    "3:4",
    "21:9",
    "9:21"
  ],
  "max_count": 4
}

image_generation

GPT Image 2

image.gpt_image_2

OpenAI GPT Image 2 — premium photorealistic generation.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16",
    "4:3",
    "3:4"
  ],
  "max_count": 4
}

image_generation

Seedream 4.5

image.seedream_v45

ByteDance Seedream 4.5 — strong product and ad visuals, photoreal.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16"
  ],
  "max_count": 4
}

image_generation

Seedream 5.0 Lite

image.seedream_v5_lite

ByteDance Seedream 5.0 Lite — multilingual text rendering, web-search-aware.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16"
  ],
  "max_count": 4
}

image_generation

Seedream 5.0 Pro

image.seedream_v5_pro

ByteDance Seedream 5.0 Pro — flagship photoreal image + multi-reference edit, up to 2K, up to 10 reference images.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16"
  ],
  "max_count": 6
}

image_generation

Qwen Image 2

image.qwen_image_2

Alibaba Qwen Image 2 — strong typography, posters, 2K generation.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16",
    "4:3",
    "3:4"
  ],
  "max_count": 4
}

image_generation

Qwen Image 2 Pro

image.qwen_image_2_pro

Premium Qwen Image 2 with enhanced detail.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16",
    "4:3",
    "3:4"
  ],
  "max_count": 4
}

image_generation

Recraft V4

image.recraft_v4

Design-grade image generation with reliable text rendering.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16",
    "4:3",
    "3:4"
  ],
  "max_count": 4
}

image_generation

Recraft V4 Pro

image.recraft_v4_pro

Premium Recraft V4 — top quality for marketing/branding visuals.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16",
    "4:3",
    "3:4"
  ],
  "max_count": 4
}

image_generation

Grok Imagine

image.grok_imagine

xAI Grok Imagine — stylized, strong prompt following.

{
  "aspect_ratios": [
    "1:1",
    "16:9",
    "9:16"
  ],
  "max_count": 4
}

video_generation

Veo 3.1

video.veo_3_1 default

Google Veo 3.1 — premium text/image-to-video with native audio. Supports first-last-frame interpolation. Default.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    4,
    5,
    8
  ],
  "supports_audio": true
}

video_generation

Veo 3.1 Fast

video.veo_3_1_fast

Cheaper, faster Veo 3.1 variant. Supports first-last-frame interpolation.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    4,
    5,
    8
  ],
  "supports_audio": true
}

video_generation

Veo 3.1 Lite

video.veo_3_1_lite

Lower-cost Lite variant of Veo 3.1. Supports first-last-frame interpolation.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    4,
    5,
    8
  ],
  "supports_audio": true
}

video_generation

Veo 3.1 Extend

video.veo_3_1_extend

Extend an existing Veo-created video by up to 7 seconds. Requires source_video_url.

{
  "aspect_ratios": [
    "16:9",
    "9:16"
  ],
  "duration_seconds": [
    7
  ],
  "supports_audio": true
}

video_generation

Veo 3

video.veo_3

Veo 3 — high-quality cinematic generation with audio (predecessor to Veo 3.1).

{
  "aspect_ratios": [
    "16:9",
    "9:16"
  ],
  "duration_seconds": [
    8
  ],
  "supports_audio": true
}

video_generation

Gemini Omni Flash

video.gemini_omni_flash

Google Gemini Omni Flash — fast, low-cost text/image-to-video. Supports reference images and video-to-video editing. 3-10s, 16:9 or 9:16. Control pacing and audio in the prompt.

{
  "aspect_ratios": [
    "16:9",
    "9:16"
  ],
  "duration_seconds": [
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10
  ],
  "supports_audio": false
}

video_generation

Veo 3 Fast

video.veo_3_fast

Cheaper Veo 3 variant — same quality tier, faster turnaround.

{
  "aspect_ratios": [
    "16:9",
    "9:16"
  ],
  "duration_seconds": [
    8
  ],
  "supports_audio": true
}

video_generation

Kling O3 Standard

video.kling_o3

Kling O3 standard — smooth motion, strong subject consistency.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    10
  ],
  "supports_audio": true
}

video_generation

Kling O3 Pro

video.kling_o3_pro

Pro tier of Kling O3 — better quality at higher cost. Supports video-to-video reference (use source_video_url + reference_image_urls).

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    10
  ],
  "supports_audio": true
}

video_generation

Kling O3 4K

video.kling_o3_4k

Kling O3 at 4K resolution. Higher cost, top-tier quality.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    10
  ],
  "resolution": "4k",
  "supports_audio": true
}

video_generation

Kling V3 Standard

video.kling_v3

Kling V3 standard.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    10
  ],
  "supports_audio": true
}

video_generation

Kling V3 Pro

video.kling_v3_pro

Kling V3 pro — top quality.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    10
  ],
  "supports_audio": true
}

video_generation

Kling V3 Motion Control

video.kling_v3_motion_control

Transfer motion from a reference video onto a character image. Requires both image_url (character) and source_video_url (motion reference).

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5
  ]
}

video_generation

Kling V3 Pro Motion Control

video.kling_v3_pro_motion_control

Pro-tier Kling V3 motion-control — higher quality character animation. Requires both image_url and source_video_url.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5
  ]
}

video_generation

Kling V3 4K

video.kling_v3_4k

Kling V3 at 4K resolution.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    10
  ],
  "resolution": "4k",
  "supports_audio": true
}

video_generation

Kling 2.6

video.kling_v26

Kling 2.6 standard — text/image to video.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    10
  ]
}

video_generation

Kling 2.6 Pro

video.kling_v26_pro

Kling 2.6 pro tier — higher quality.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    10
  ]
}

video_generation

Kling 2.6 Motion Control

video.kling_v26_motion_control

Motion-control variant of Kling 2.6 (legacy). Requires image_url + source_video_url.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5
  ]
}

video_generation

Kling 2.5 Turbo Pro

video.kling_v25_turbo

Faster Kling variant (legacy but reliable).

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    10
  ]
}

video_generation

Kling 2.1 Master

video.kling_v21_master

Kling 2.1 Master (legacy) — enhanced quality.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    10
  ]
}

video_generation

Sora 2

video.sora_2

OpenAI Sora 2 — text and image to video, 4–20s.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    4,
    8,
    12,
    16,
    20
  ]
}

video_generation

Hailuo 2.3

video.hailuo_23

MiniMax Hailuo 2.3 — dynamic video generation.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    6,
    10
  ]
}

video_generation

Hailuo 2.3 Pro

video.hailuo_23_pro

MiniMax Hailuo 2.3 Pro tier.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    6,
    10
  ]
}

video_generation

Hailuo 02

video.hailuo_02

MiniMax Hailuo 02 (legacy) — image-to-video standard tier.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    6,
    10
  ]
}

video_generation

Hailuo 02 Fast

video.hailuo_02_fast

Faster Hailuo 02 image-to-video variant.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    6,
    10
  ]
}

video_generation

Hailuo 2.3 Fast

video.hailuo_23_fast

Faster Hailuo 2.3 image-to-video standard tier.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    6,
    10
  ]
}

video_generation

Hailuo 2.3 Fast Pro

video.hailuo_23_fast_pro

Faster Hailuo 2.3 pro-tier image-to-video.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    6,
    10
  ]
}

video_generation

Luma Dream Machine

video.luma_dream_machine

Luma Dream Machine — fluid motion, distinctive style.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    9
  ]
}

video_generation

WAN 2.2

video.wan_v22

WAN 2.2 — strong character animation.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    8
  ]
}

video_generation

WAN 2.5 Preview

video.wan_25_preview

WAN 2.5 preview — newer than 2.2, may change without notice.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5,
    8
  ]
}

video_generation

WAN Animate (Replace)

video.wan_animate_replace

WAN animate-replace — swap subject in source video using a reference image. Requires image_url + source_video_url.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5
  ]
}

video_generation

WAN Animate (Move)

video.wan_animate_move

WAN animate-move — animate static images with natural motion from a reference video. Requires image_url + source_video_url.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    5
  ]
}

video_generation

Seedance 2.0

video.seedance_2_0

ByteDance Seedance 2.0 — text/image/reference to video. Supports up to 4k.

{
  "aspect_ratios": [
    "auto",
    "21:9",
    "16:9",
    "4:3",
    "1:1",
    "3:4",
    "9:16"
  ],
  "duration_seconds": [
    4,
    5,
    6,
    7,
    8,
    9,
    10,
    11,
    12,
    13,
    14,
    15
  ],
  "resolutions": [
    "480p",
    "720p",
    "1080p",
    "4k"
  ],
  "supports_audio": true
}

video_generation

Seedance 2.0 Fast

video.seedance_2_0_fast

Faster, cheaper Seedance 2.0 variant. Caps at 720p.

{
  "aspect_ratios": [
    "auto",
    "21:9",
    "16:9",
    "4:3",
    "1:1",
    "3:4",
    "9:16"
  ],
  "duration_seconds": [
    4,
    5,
    6,
    7,
    8,
    9,
    10,
    11,
    12,
    13,
    14,
    15
  ],
  "resolutions": [
    "480p",
    "720p"
  ],
  "supports_audio": true
}

video_generation

Seedance 2.0 Mini

video.seedance_2_0_mini

Smallest, cheapest Seedance 2.0 variant. Caps at 720p; no bitrate_mode.

{
  "aspect_ratios": [
    "auto",
    "21:9",
    "16:9",
    "4:3",
    "1:1",
    "3:4",
    "9:16"
  ],
  "duration_seconds": [
    4,
    5,
    6,
    7,
    8,
    9,
    10,
    11,
    12,
    13,
    14,
    15
  ],
  "resolutions": [
    "480p",
    "720p"
  ],
  "supports_audio": true
}

video_generation

Grok Imagine Video

video.grok_video

xAI Grok Imagine — high-fidelity text/image to video.

{
  "aspect_ratios": [
    "16:9",
    "4:3",
    "3:2",
    "1:1",
    "2:3",
    "3:4",
    "9:16"
  ],
  "duration_seconds": [
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10
  ],
  "resolutions": [
    "480p",
    "720p"
  ]
}

video_generation

Grok Imagine Video v1.5

video.grok_video_v15

xAI Grok Imagine v1.5 — image-to-video. Requires image_url.

{
  "duration_seconds": [
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10,
    11,
    12,
    13,
    14,
    15
  ],
  "resolutions": [
    "480p",
    "720p",
    "1080p"
  ]
}

video_generation

Grok Imagine Edit

video.grok_video_edit

Edit existing videos with text prompts. Requires source_video_url.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    4,
    5,
    8,
    10
  ]
}

video_generation

Grok Imagine Extend

video.grok_video_extend

Extend an existing video by 2–10s. Requires source_video_url.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "duration_seconds": [
    2,
    5,
    10
  ]
}

video_generation

Happy Horse v1.1

video.happy_horse

Alibaba Happy Horse v1.1 — text/image/reference-to-video, plus video-edit.

{
  "aspect_ratios": [
    "16:9",
    "9:16",
    "1:1",
    "4:3",
    "3:4",
    "21:9",
    "9:21",
    "5:4",
    "4:5"
  ],
  "duration_seconds": [
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10,
    11,
    12,
    13,
    14,
    15
  ]
}

speech_generation

ElevenLabs Turbo v2.5

speech.elevenlabs_turbo_v2_5 default

Low-latency TTS, balance of quality and speed. Default.

{
  "max_characters": 40000
}

speech_generation

ElevenLabs Flash v2.5

speech.elevenlabs_flash_v2_5

Fastest ElevenLabs TTS, lowest cost.

{
  "max_characters": 40000
}

speech_generation

ElevenLabs v3

speech.elevenlabs_v3

Highest-quality expressive voice generation.

{
  "max_characters": 40000
}

speech_generation

ElevenLabs Multilingual v2

speech.elevenlabs_multilingual_v2

29 languages, high fidelity.

{
  "max_characters": 40000
}

speech_generation

Seed Audio 1.0

speech.seed_audio_1_0

ByteDance Seed Audio 1.0 — general text-to-audio: natural multilingual TTS plus full audio scenes (dialogue, ambience, radio dramas) from a prompt. voice_id is OPTIONAL and takes a Seed preset name (e.g. `vivi_mixed_en_zh_ja_es_id`, `mindy_en_es_id_pt_zh`, `kian_en_zh`, `sophie_en_zh`, `magnus_en_zh`) — NOT an ElevenLabs/cloned voice id; omit it to let the model narrate. Accepts up to 3 reference audio clips via audio_urls (reference them in the prompt as @Audio1–@Audio3) OR one reference image via image_url, plus speed/volume/pitch, output_format (wav|mp3|pcm|ogg_opus) and sample_rate. Billed per second (billed seconds ≈ ceil(text length / 15)).

{
  "max_characters": 2048,
  "max_reference_audio": 3
}

music_generation

ElevenLabs Music v1

music.elevenlabs_music_v1 default

Prompt-based music generation up to 10 minutes. Also accepts a `composition_plan` (MusicPrompt: positive/negative_global_styles + sections[] with lyrics lines) instead of a prompt for full structural control; `respect_sections_durations` controls how strictly section durations are enforced.

{
  "max_duration_seconds": 600
}

music_generation

ElevenLabs Music v2

music.elevenlabs_music_v2

ElevenLabs music_v2 — higher-quality music generation up to 10 minutes from a prompt, or a chunk-based `composition_plan` (chunks[] with text incl. [Section]/{direction} markup, duration_ms, positive/negative_styles, optional per-chunk audio conditioning refs + `seed`).

{
  "max_duration_seconds": 600
}

music_generation

Lyria 3 Pro

music.lyria3_pro

Google Lyria 3 Pro — full structured songs up to 3 minutes with vocals, lyrics, and multi-language support. Accepts an optional image_url for inspiration and a negative_prompt. Flat per-generation fee (duration is not configurable).

{
  "max_duration_seconds": 180,
  "prompt_max_length": 5000
}

sound_effect_generation

ElevenLabs SFX

sfx.elevenlabs_v1 default

Sound effect generation up to 30s.

{
  "max_duration_seconds": 30
}

transcription

OpenAI Whisper v1

transcription.whisper_v1 default

Speech-to-text with word and segment timestamps. Accepts a direct audio/video URL or a YouTube URL. Async — returns a queued run; poll genfire_get_run for the transcript.

{
  "max_file_mb": 500,
  "max_duration_seconds": 7200
}

image_editing

BRIA Background Remove

image_edit.bria_background_remove default

Remove the background from an image. Returns a transparent PNG.

{
  "input": "image_url"
}

video_upscaling

FAL Video Upscaler

video_upscale.fal_video_upscaler default

Upscale a video by 2x or 4x. Async — returns a queued run; poll genfire_get_run for completion.

{
  "scale_factors": [
    2,
    4
  ]
}

image_upscaling

FAL Topaz Upscale

image_upscale.topaz_upscale_image default

Upscale an image by 2x or 4x. Async — returns a queued run; poll genfire_get_run for completion.

{
  "scale_factors": [
    2,
    4
  ]
}

lipsync_generation

Lipsync 2 Pro

lipsync.lipsync_2_pro default

High-quality lip-sync at 480p or 720p. Default.

{
  "resolutions": [
    "480p",
    "720p"
  ]
}

lipsync_generation

Sync Lipsync v2 Pro

lipsync.sync_lipsync_v2_pro

Alternative lip-sync engine.

{
  "resolutions": [
    "480p",
    "720p"
  ]
}

lipsync_generation

Sync Lipsync v3

lipsync.sync_lipsync_v3

Premium lip-sync engine — higher fidelity than v2 Pro.

{
  "resolutions": [
    "480p",
    "720p"
  ]
}

model_3d_generation

Meshy v6

3d.meshy_v6 default

Convert one image (or 1–4 images of the same object from different angles) into a textured 3D model. Outputs GLB/FBX/OBJ/USDZ/BLEND/STL plus optional PBR maps, auto-rigging, and animation. Game-ready — GLB loads natively in three.js / model-viewer. Async — returns a queued run; poll genfire_get_run for the model URLs. Processing takes 5–10 minutes.

{
  "max_images": 4,
  "output_formats": [
    "glb",
    "fbx",
    "obj",
    "usdz",
    "blend",
    "stl"
  ],
  "target_polycount": {
    "min": 100,
    "max": 300000,
    "default": 30000
  },
  "topology": [
    "quad",
    "triangle"
  ]
}

game_generation

GenFire Games

game.genfire_v1 default

Describe a game and get a fully-playable browser game (self-contained HTML, Phaser/canvas/Three.js). The completed run carries a public play_url you can open or share. Iterate by passing game_id with a change prompt. Async — returns a queued run; the codegen runs on a worker (usually 1–3 min). Poll GET /runs/{id} until status is completed, then read output.play_url.

{
  "output": "playable_html",
  "shareable": true
}

app_generation

GenFire App Builder

app.genfire_v1 default

Describe an app and get a working full-stack single-file web app (UI + in-browser data layer, hosted live). The completed run carries a public live_url you can open or share. Iterate by passing app_id with a change prompt. Async — returns a queued run; codegen runs on a worker (usually 1–3 min). Poll GET /runs/{id} until status is completed, then read output.live_url.

{
  "output": "live_web_app",
  "shareable": true
}

faceless_reel_generation

Faceless Reel

reel.faceless default

End-to-end vertical (9:16) short: LLM script → voiceover → style-locked images → music → captioned video. Driven by a niche preset + visual style; cost varies with duration and music — call POST /v1/faceless-reels/estimate-cost for a per-config estimate.

{
  "aspect_ratios": [
    "9:16"
  ],
  "target_duration_sec": {
    "min": 10,
    "max": 120,
    "default": null
  },
  "music_sources": [
    "none",
    "preset",
    "ai",
    "library"
  ],
  "catalogs": [
    "presets",
    "styles",
    "music-presets",
    "caption-presets"
  ]
}

explainer_generation

Explainer

explainer.omni default

Long-form narrated explainer/documentary (20s–10min, 16:9 or 9:16): script → expressive voiceover → style-locked frames → Gemini Omni Flash video clips → composed film with optional captions. Pass `script` (structured beats) to author the entire creative contract with YOUR OWN model — narration, per-scene shot-specs, motion notes, render modes, reference routing, emphasis words and recurring cast — and GenFire only renders; or pass just `topic` and GenFire writes the script. Cost varies with duration — call POST /v1/explainers/estimate-cost first.

{
  "aspect_ratios": [
    "16:9",
    "9:16"
  ],
  "target_duration_sec": {
    "min": 20,
    "max": 600,
    "default": 60
  },
  "music_sources": [
    "none",
    "preset",
    "ai",
    "library"
  ],
  "script_beats": {
    "min": 3,
    "max": 100
  },
  "reference_images": {
    "max": 8
  },
  "cast_members": {
    "max": 3
  },
  "caption_modes": [
    "full",
    "keywords"
  ],
  "caption_positions": [
    "top",
    "middle",
    "bottom"
  ],
  "catalogs": [
    "styles"
  ]
}

Outcome Layer

Workflow Catalog

Use workflows when you want a business outcome such as hook generation, a creative pack, or UGC ad variants instead of a raw media primitive.

Workflow

`hook_pack`

available

Generate three monetizable UGC-style hooks plus a supporting body and CTA.

Input Schema

{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string"
    },
    "audience": {
      "type": "string"
    },
    "tone": {
      "type": "string",
      "enum": [
        "casual",
        "professional",
        "humorous",
        "educational",
        "persuasive",
        "emotional"
      ]
    },
    "length": {
      "type": "string",
      "enum": [
        "short",
        "medium",
        "long"
      ]
    },
    "target_duration": {
      "type": "number"
    },
    "keywords": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "additional_requirements": {
      "type": "string"
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "hooks": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "body": {
      "type": "string"
    },
    "call_to_action": {
      "type": "string"
    },
    "full_script": {
      "type": "string"
    }
  }
}

Example Request Body

{
  "prompt": "Portable blender for busy professionals",
  "audience": "Remote workers who skip breakfast",
  "tone": "persuasive",
  "length": "short",
  "target_duration": 20,
  "keywords": [
    "protein shake",
    "commute",
    "healthy"
  ],
  "additional_requirements": "Lead with convenience and save time."
}

Example Output

{
  "workflow": "hook_pack",
  "topic": "Portable blender for busy professionals",
  "hooks": [
    "If breakfast keeps losing to your calendar, this fixes it.",
    "I stopped skipping protein the day I threw this in my bag.",
    "This is how I make a full shake before my first meeting."
  ],
  "body": "Portable, fast, and easy to clean for daily use.",
  "call_to_action": "Try it before your next busy week.",
  "full_script": "If breakfast keeps losing to your calendar...",
  "word_count": 96,
  "estimated_duration": 22
}

Workflow

`ugc_ad`

available

Generate an outcome-oriented UGC ad script with hooks, body, CTA, and a full spoken script.

Input Schema

{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string"
    },
    "audience": {
      "type": "string"
    },
    "tone": {
      "type": "string",
      "enum": [
        "casual",
        "professional",
        "humorous",
        "educational",
        "persuasive",
        "emotional"
      ]
    },
    "length": {
      "type": "string",
      "enum": [
        "short",
        "medium",
        "long"
      ]
    },
    "target_duration": {
      "type": "number"
    },
    "keywords": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "additional_requirements": {
      "type": "string"
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "hooks": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "body": {
      "type": "string"
    },
    "call_to_action": {
      "type": "string"
    },
    "full_script": {
      "type": "string"
    }
  }
}

Example Request Body

{
  "prompt": "Blue light glasses for creators",
  "audience": "Designers and editors working late",
  "tone": "casual",
  "length": "medium"
}

Example Output

{
  "workflow": "ugc_ad",
  "topic": "Blue light glasses for creators",
  "hooks": [
    "I did not realize how cooked my eyes were by 6pm."
  ],
  "body": "Comfort-focused UGC body copy.",
  "call_to_action": "Use them on your next edit sprint.",
  "full_script": "I did not realize how cooked my eyes were..."
}

Workflow

`creative_pack`

available

Build a product-aware creative pack with analysis, angles, hooks, and a monetizable script.

Input Schema

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string"
    },
    "product_url": {
      "type": "string",
      "format": "uri"
    },
    "product_name": {
      "type": "string"
    },
    "product_description": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "audience": {
      "type": "string"
    },
    "tone": {
      "type": "string",
      "enum": [
        "casual",
        "professional",
        "humorous",
        "educational",
        "persuasive",
        "emotional"
      ]
    },
    "length": {
      "type": "string",
      "enum": [
        "short",
        "medium",
        "long"
      ]
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      }
    },
    "additional_requirements": {
      "type": "string"
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "product": {
      "type": "object"
    },
    "analysis": {
      "type": "object"
    },
    "hooks": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "body": {
      "type": "string"
    },
    "call_to_action": {
      "type": "string"
    },
    "full_script": {
      "type": "string"
    }
  }
}

Example Request Body

{
  "product_url": "https://example.com/products/matte-black-water-bottle"
}

Example Output

{
  "workflow": "creative_pack",
  "product": {
    "name": "Matte Black Water Bottle",
    "description": "Insulated stainless steel water bottle",
    "category": "hydration",
    "price": "$39",
    "images": [
      "https://example.com/image-1.jpg"
    ]
  },
  "analysis": {
    "marketingAngles": [
      "Premium feel",
      "Keeps drinks cold",
      "Daily carry convenience"
    ]
  },
  "hooks": [
    "This bottle still had ice after my entire workout and commute."
  ],
  "body": "Creative body copy built from product analysis.",
  "call_to_action": "Upgrade your daily carry.",
  "full_script": "This bottle still had ice..."
}

Workflow

`product_ad_variants`

available

Generate multiple UGC-style ad script variants for the same product or offer.

Input Schema

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string"
    },
    "product_name": {
      "type": "string"
    },
    "product_description": {
      "type": "string"
    },
    "audience": {
      "type": "string"
    },
    "tone": {
      "type": "string",
      "enum": [
        "casual",
        "professional",
        "humorous",
        "educational",
        "persuasive",
        "emotional"
      ]
    },
    "length": {
      "type": "string",
      "enum": [
        "short",
        "medium",
        "long"
      ]
    },
    "variant_count": {
      "type": "number",
      "minimum": 1,
      "maximum": 5
    },
    "additional_requirements": {
      "type": "string"
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "variant_count": {
      "type": "number"
    },
    "variants": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  }
}

Example Request Body

{
  "product_name": "Portable espresso maker",
  "product_description": "Travel-friendly espresso maker for commuters",
  "audience": "Commuters and travelers",
  "tone": "persuasive",
  "length": "short",
  "variant_count": 3
}

Example Output

{
  "workflow": "product_ad_variants",
  "prompt": "Portable espresso maker: Travel-friendly espresso maker for commuters",
  "variant_count": 3,
  "variants": [
    {
      "index": 0,
      "strategy": "Question-led hook with direct pain point.",
      "hooks": [
        "Why are you still settling for station coffee?"
      ],
      "body": "Variant body",
      "call_to_action": "Carry café-level espresso anywhere.",
      "full_script": "Why are you still settling for station coffee?"
    }
  ]
}

Reference

Authentication

POST /oauth/token

Issue an OAuth access token

Use OAuth client credentials for machine-to-machine access. API keys are supported on the same `/v1` endpoints and are usually the simplest option.

Auth: No auth

Idempotency-Key: Not required

Body Fields

grant_type string required

Must be `client_credentials`.

client_id string required

The OAuth client id created in the developer portal.

client_secret string required

The OAuth client secret shown only when the client is created.

scope string optional

Optional space-separated scopes. Omit to receive the client’s default scopes.

curl Example

curl https://api.genfire.ai/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
  "grant_type": "client_credentials",
  "client_id": "gfo_oauth_123",
  "client_secret": "gfs_live_secret",
  "scope": "models:read runs:read images:write"
}'

Response Example

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "models:read runs:read images:write"
}

Request Example Body

{
  "grant_type": "client_credentials",
  "client_id": "gfo_oauth_123",
  "client_secret": "gfs_live_secret",
  "scope": "models:read runs:read images:write"
}

Notes

You can also send `client_id:client_secret` with HTTP Basic auth instead of putting them in JSON.
The returned access token is used in the same `Authorization: Bearer ...` header as an API key.

Reference

CLI Auth

POST /cli/auth/sessions

Start a CLI auth session

Begins the browser-based PKCE handshake used by the GenFire CLI. The CLI generates a 43-128 character base64url `code_verifier`, derives `code_challenge = BASE64URL(SHA256(verifier))`, calls this endpoint, and opens `verification_url` in the user’s browser.

Auth: No auth

Idempotency-Key: Not required

Body Fields

client_id string required

Public CLI client id. Currently only `genfire-cli`.

code_challenge string required

BASE64URL(SHA256(code_verifier)). 43-128 characters.

code_challenge_method string required

Must be `S256`.

scopes array optional

Optional list of scopes the CLI is requesting. Omit for the default key scopes.

label string optional

Optional human label shown to the user on the consent page (e.g. `genfire-cli (laptop)`).

curl Example

curl https://api.genfire.ai/v1/cli/auth/sessions \
  -H "Content-Type: application/json" \
  -d '{
  "client_id": "genfire-cli",
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "code_challenge_method": "S256",
  "scopes": [
    "account:read",
    "credits:read",
    "models:read",
    "runs:read",
    "images:write",
    "videos:write",
    "uploads:write"
  ],
  "label": "genfire-cli (laptop)"
}'

Response Example

{
  "session_id": "clisess_8f3c4a2b1d6e7f9a0b1c2d3e",
  "verification_url": "https://genfire.ai/cli-auth?session=clisess_8f3c4a2b1d6e7f9a0b1c2d3e",
  "expires_at": "2026-05-04T17:21:25.985Z",
  "requested_scopes": [
    "account:read",
    "images:write",
    "uploads:write"
  ],
  "label": "genfire-cli (laptop)"
}

Request Example Body

{
  "client_id": "genfire-cli",
  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
  "code_challenge_method": "S256",
  "scopes": [
    "account:read",
    "credits:read",
    "models:read",
    "runs:read",
    "images:write",
    "videos:write",
    "uploads:write"
  ],
  "label": "genfire-cli (laptop)"
}

Notes

Sessions expire after 10 minutes if not approved.
Poll `GET /cli/auth/sessions/{sessionId}` to discover when the user has approved (or denied) the session.

GET /cli/auth/sessions/{sessionId}

Poll the status of a CLI auth session

Returns the current status of a CLI auth session. The CLI polls this endpoint while the user completes the browser flow.

Auth: No auth

Idempotency-Key: Not required

Parameters

sessionId path required

Session id returned from `POST /cli/auth/sessions`.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/cli/auth/sessions/{sessionId}

Response Example

{
  "session_id": "clisess_8f3c4a2b1d6e7f9a0b1c2d3e",
  "status": "approved",
  "label": "genfire-cli (laptop)",
  "requested_scopes": [
    "account:read",
    "images:write",
    "uploads:write"
  ],
  "expires_at": "2026-05-04T17:21:25.985Z"
}

Notes

Status transitions: `pending` → `approved` (or `denied`) → `consumed` (after exchange).
A `consumed` or `expired` status means the CLI must restart the login flow.

POST /cli/auth/sessions/{sessionId}/exchange

Exchange an approved CLI auth session for an API key

Once `GET /cli/auth/sessions/{sessionId}` reports `approved`, the CLI submits its original `code_verifier` here. The server verifies `SHA256(code_verifier) === code_challenge`, then returns the freshly minted API key exactly once.

Auth: No auth

Idempotency-Key: Not required

Parameters

sessionId path required

Session id returned from `POST /cli/auth/sessions`.

Body Fields

code_verifier string required

The original PKCE code_verifier the CLI generated when starting the session.

curl Example

curl https://api.genfire.ai/v1/cli/auth/sessions/{sessionId}/exchange \
  -H "Content-Type: application/json" \
  -d '{
  "code_verifier": "M25iVXpKU3puUjFaYWg3T1NDTDQtcW1ROUY5YXlwalNoc0hhakxifmZHag"
}'

Response Example

{
  "api_key": "gfa_live_abc123.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scopes": [
    "account:read",
    "images:write",
    "uploads:write"
  ],
  "label": "genfire-cli (laptop)",
  "session_expires_at": "2026-05-04T17:21:25.985Z"
}

Request Example Body

{
  "code_verifier": "M25iVXpKU3puUjFaYWg3T1NDTDQtcW1ROUY5YXlwalNoc0hhakxifmZHag"
}

Notes

The `api_key` is returned exactly once. Store it securely (the CLI uses the OS keychain).
Sessions are single-use. Once exchanged, the same session cannot be exchanged again.
A 428 response means the user has not yet approved the session — keep polling.
A 410 response means the session expired or was already exchanged. Restart the CLI login.

Reference

Account

GET /account

account:read

Get the authenticated account

Returns the public API account linked to the calling API key or OAuth client.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "id": "acct_user_123",
  "object": "account",
  "display_name": "GenFire Developer",
  "email": "owner@example.com",
  "plan": "pro",
  "status": "active",
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:00.000Z"
}

GET /account/credits

credits:read

Get the current credit balance

Shows the credit balance for the authenticated account.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/account/credits \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "account_id": "acct_user_123",
  "balance": 250,
  "currency": "credits"
}

Reference

Discovery

GET /models

models:read

List public model aliases

Use model aliases from this endpoint instead of internal provider ids. The aliases are stable and safe to pass back into generation endpoints.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "image.genfire_v1",
      "object": "model",
      "capability": "image_generation",
      "name": "GenFire v1",
      "description": "GenFire's signature image model — tuned for ad/product creative.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.nano_banana_2",
      "object": "model",
      "capability": "image_generation",
      "name": "Nano Banana 2",
      "description": "Google's general-purpose image model. Fast, broad subject coverage. Default.",
      "status": "available",
      "is_default": true,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4",
          "21:9",
          "9:21"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.nano_banana_pro",
      "object": "model",
      "capability": "image_generation",
      "name": "Nano Banana Pro",
      "description": "Premium photoreal image generation, higher fidelity than Nano Banana 2.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.nano_banana",
      "object": "model",
      "capability": "image_generation",
      "name": "Nano Banana",
      "description": "Standard speed and quality. Cheaper than Pro for high-volume use.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.nano_banana_lite",
      "object": "model",
      "capability": "image_generation",
      "name": "Nano Banana Lite",
      "description": "Gemini 3.1 Flash Lite Image — ultra-low latency, cheapest tier. Supports editing.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4",
          "21:9",
          "9:21"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.nano_banana_2_lite",
      "object": "model",
      "capability": "image_generation",
      "name": "Nano Banana 2 Lite",
      "description": "Gemini 3.1 Flash Lite Image (v2) — ultra-low latency text-to-image. No edit endpoint.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4",
          "21:9",
          "9:21"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": false,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.gpt_image_2",
      "object": "model",
      "capability": "image_generation",
      "name": "GPT Image 2",
      "description": "OpenAI GPT Image 2 — premium photorealistic generation.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.seedream_v45",
      "object": "model",
      "capability": "image_generation",
      "name": "Seedream 4.5",
      "description": "ByteDance Seedream 4.5 — strong product and ad visuals, photoreal.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.seedream_v5_lite",
      "object": "model",
      "capability": "image_generation",
      "name": "Seedream 5.0 Lite",
      "description": "ByteDance Seedream 5.0 Lite — multilingual text rendering, web-search-aware.",
      "status": "preview",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.seedream_v5_pro",
      "object": "model",
      "capability": "image_generation",
      "name": "Seedream 5.0 Pro",
      "description": "ByteDance Seedream 5.0 Pro — flagship photoreal image + multi-reference edit, up to 2K, up to 10 reference images.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "max_count": 6
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.qwen_image_2",
      "object": "model",
      "capability": "image_generation",
      "name": "Qwen Image 2",
      "description": "Alibaba Qwen Image 2 — strong typography, posters, 2K generation.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.qwen_image_2_pro",
      "object": "model",
      "capability": "image_generation",
      "name": "Qwen Image 2 Pro",
      "description": "Premium Qwen Image 2 with enhanced detail.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.recraft_v4",
      "object": "model",
      "capability": "image_generation",
      "name": "Recraft V4",
      "description": "Design-grade image generation with reliable text rendering.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": false,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.recraft_v4_pro",
      "object": "model",
      "capability": "image_generation",
      "name": "Recraft V4 Pro",
      "description": "Premium Recraft V4 — top quality for marketing/branding visuals.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16",
          "4:3",
          "3:4"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": false,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "image.grok_imagine",
      "object": "model",
      "capability": "image_generation",
      "name": "Grok Imagine",
      "description": "xAI Grok Imagine — stylized, strong prompt following.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "max_count": 4
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.veo_3_1",
      "object": "model",
      "capability": "video_generation",
      "name": "Veo 3.1",
      "description": "Google Veo 3.1 — premium text/image-to-video with native audio. Supports first-last-frame interpolation. Default.",
      "status": "available",
      "is_default": true,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          4,
          5,
          8
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": true,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": true
      }
    },
    {
      "id": "video.veo_3_1_fast",
      "object": "model",
      "capability": "video_generation",
      "name": "Veo 3.1 Fast",
      "description": "Cheaper, faster Veo 3.1 variant. Supports first-last-frame interpolation.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          4,
          5,
          8
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": true
      }
    },
    {
      "id": "video.veo_3_1_lite",
      "object": "model",
      "capability": "video_generation",
      "name": "Veo 3.1 Lite",
      "description": "Lower-cost Lite variant of Veo 3.1. Supports first-last-frame interpolation.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          4,
          5,
          8
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": true
      }
    },
    {
      "id": "video.veo_3_1_extend",
      "object": "model",
      "capability": "video_generation",
      "name": "Veo 3.1 Extend",
      "description": "Extend an existing Veo-created video by up to 7 seconds. Requires source_video_url.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16"
        ],
        "duration_seconds": [
          7
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": false,
        "reference_images": false,
        "source_video": true,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.veo_3",
      "object": "model",
      "capability": "video_generation",
      "name": "Veo 3",
      "description": "Veo 3 — high-quality cinematic generation with audio (predecessor to Veo 3.1).",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16"
        ],
        "duration_seconds": [
          8
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.gemini_omni_flash",
      "object": "model",
      "capability": "video_generation",
      "name": "Gemini Omni Flash",
      "description": "Google Gemini Omni Flash — fast, low-cost text/image-to-video. Supports reference images and video-to-video editing. 3-10s, 16:9 or 9:16. Control pacing and audio in the prompt.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16"
        ],
        "duration_seconds": [
          3,
          4,
          5,
          6,
          7,
          8,
          9,
          10
        ],
        "supports_audio": false
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": true,
        "source_video": true,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.veo_3_fast",
      "object": "model",
      "capability": "video_generation",
      "name": "Veo 3 Fast",
      "description": "Cheaper Veo 3 variant — same quality tier, faster turnaround.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16"
        ],
        "duration_seconds": [
          8
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_o3",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling O3 Standard",
      "description": "Kling O3 standard — smooth motion, strong subject consistency.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          10
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": true,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_o3_pro",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling O3 Pro",
      "description": "Pro tier of Kling O3 — better quality at higher cost. Supports video-to-video reference (use source_video_url + reference_image_urls).",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          10
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": true,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_o3_4k",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling O3 4K",
      "description": "Kling O3 at 4K resolution. Higher cost, top-tier quality.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          10
        ],
        "resolution": "4k",
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": true,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_v3",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling V3 Standard",
      "description": "Kling V3 standard.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          10
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_v3_pro",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling V3 Pro",
      "description": "Kling V3 pro — top quality.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          10
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_v3_motion_control",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling V3 Motion Control",
      "description": "Transfer motion from a reference video onto a character image. Requires both image_url (character) and source_video_url (motion reference).",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": false,
        "reference_images": false,
        "source_video": false,
        "motion_control": true,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_v3_pro_motion_control",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling V3 Pro Motion Control",
      "description": "Pro-tier Kling V3 motion-control — higher quality character animation. Requires both image_url and source_video_url.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": false,
        "reference_images": false,
        "source_video": false,
        "motion_control": true,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_v3_4k",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling V3 4K",
      "description": "Kling V3 at 4K resolution.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          10
        ],
        "resolution": "4k",
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_v26",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling 2.6",
      "description": "Kling 2.6 standard — text/image to video.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          10
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_v26_pro",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling 2.6 Pro",
      "description": "Kling 2.6 pro tier — higher quality.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          10
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": true,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_v26_motion_control",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling 2.6 Motion Control",
      "description": "Motion-control variant of Kling 2.6 (legacy). Requires image_url + source_video_url.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": false,
        "reference_images": false,
        "source_video": false,
        "motion_control": true,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_v25_turbo",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling 2.5 Turbo Pro",
      "description": "Faster Kling variant (legacy but reliable).",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          10
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.kling_v21_master",
      "object": "model",
      "capability": "video_generation",
      "name": "Kling 2.1 Master",
      "description": "Kling 2.1 Master (legacy) — enhanced quality.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          10
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.sora_2",
      "object": "model",
      "capability": "video_generation",
      "name": "Sora 2",
      "description": "OpenAI Sora 2 — text and image to video, 4–20s.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          4,
          8,
          12,
          16,
          20
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.hailuo_23",
      "object": "model",
      "capability": "video_generation",
      "name": "Hailuo 2.3",
      "description": "MiniMax Hailuo 2.3 — dynamic video generation.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          6,
          10
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.hailuo_23_pro",
      "object": "model",
      "capability": "video_generation",
      "name": "Hailuo 2.3 Pro",
      "description": "MiniMax Hailuo 2.3 Pro tier.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          6,
          10
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.hailuo_02",
      "object": "model",
      "capability": "video_generation",
      "name": "Hailuo 02",
      "description": "MiniMax Hailuo 02 (legacy) — image-to-video standard tier.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          6,
          10
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.hailuo_02_fast",
      "object": "model",
      "capability": "video_generation",
      "name": "Hailuo 02 Fast",
      "description": "Faster Hailuo 02 image-to-video variant.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          6,
          10
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.hailuo_23_fast",
      "object": "model",
      "capability": "video_generation",
      "name": "Hailuo 2.3 Fast",
      "description": "Faster Hailuo 2.3 image-to-video standard tier.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          6,
          10
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.hailuo_23_fast_pro",
      "object": "model",
      "capability": "video_generation",
      "name": "Hailuo 2.3 Fast Pro",
      "description": "Faster Hailuo 2.3 pro-tier image-to-video.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          6,
          10
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.luma_dream_machine",
      "object": "model",
      "capability": "video_generation",
      "name": "Luma Dream Machine",
      "description": "Luma Dream Machine — fluid motion, distinctive style.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          9
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.wan_v22",
      "object": "model",
      "capability": "video_generation",
      "name": "WAN 2.2",
      "description": "WAN 2.2 — strong character animation.",
      "status": "preview",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          8
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.wan_25_preview",
      "object": "model",
      "capability": "video_generation",
      "name": "WAN 2.5 Preview",
      "description": "WAN 2.5 preview — newer than 2.2, may change without notice.",
      "status": "preview",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5,
          8
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.wan_animate_replace",
      "object": "model",
      "capability": "video_generation",
      "name": "WAN Animate (Replace)",
      "description": "WAN animate-replace — swap subject in source video using a reference image. Requires image_url + source_video_url.",
      "status": "preview",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": false,
        "reference_images": false,
        "source_video": false,
        "motion_control": true,
        "first_last_frame": false
      }
    },
    {
      "id": "video.wan_animate_move",
      "object": "model",
      "capability": "video_generation",
      "name": "WAN Animate (Move)",
      "description": "WAN animate-move — animate static images with natural motion from a reference video. Requires image_url + source_video_url.",
      "status": "preview",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          5
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": false,
        "reference_images": false,
        "source_video": false,
        "motion_control": true,
        "first_last_frame": false
      }
    },
    {
      "id": "video.seedance_2_0",
      "object": "model",
      "capability": "video_generation",
      "name": "Seedance 2.0",
      "description": "ByteDance Seedance 2.0 — text/image/reference to video. Supports up to 4k.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "auto",
          "21:9",
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16"
        ],
        "duration_seconds": [
          4,
          5,
          6,
          7,
          8,
          9,
          10,
          11,
          12,
          13,
          14,
          15
        ],
        "resolutions": [
          "480p",
          "720p",
          "1080p",
          "4k"
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": true,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.seedance_2_0_fast",
      "object": "model",
      "capability": "video_generation",
      "name": "Seedance 2.0 Fast",
      "description": "Faster, cheaper Seedance 2.0 variant. Caps at 720p.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "auto",
          "21:9",
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16"
        ],
        "duration_seconds": [
          4,
          5,
          6,
          7,
          8,
          9,
          10,
          11,
          12,
          13,
          14,
          15
        ],
        "resolutions": [
          "480p",
          "720p"
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": true,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.seedance_2_0_mini",
      "object": "model",
      "capability": "video_generation",
      "name": "Seedance 2.0 Mini",
      "description": "Smallest, cheapest Seedance 2.0 variant. Caps at 720p; no bitrate_mode.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "auto",
          "21:9",
          "16:9",
          "4:3",
          "1:1",
          "3:4",
          "9:16"
        ],
        "duration_seconds": [
          4,
          5,
          6,
          7,
          8,
          9,
          10,
          11,
          12,
          13,
          14,
          15
        ],
        "resolutions": [
          "480p",
          "720p"
        ],
        "supports_audio": true
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": true,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.grok_video",
      "object": "model",
      "capability": "video_generation",
      "name": "Grok Imagine Video",
      "description": "xAI Grok Imagine — high-fidelity text/image to video.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "4:3",
          "3:2",
          "1:1",
          "2:3",
          "3:4",
          "9:16"
        ],
        "duration_seconds": [
          1,
          2,
          3,
          4,
          5,
          6,
          7,
          8,
          9,
          10
        ],
        "resolutions": [
          "480p",
          "720p"
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": true,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.grok_video_v15",
      "object": "model",
      "capability": "video_generation",
      "name": "Grok Imagine Video v1.5",
      "description": "xAI Grok Imagine v1.5 — image-to-video. Requires image_url.",
      "status": "available",
      "is_default": false,
      "limits": {
        "duration_seconds": [
          1,
          2,
          3,
          4,
          5,
          6,
          7,
          8,
          9,
          10,
          11,
          12,
          13,
          14,
          15
        ],
        "resolutions": [
          "480p",
          "720p",
          "1080p"
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.grok_video_edit",
      "object": "model",
      "capability": "video_generation",
      "name": "Grok Imagine Edit",
      "description": "Edit existing videos with text prompts. Requires source_video_url.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          4,
          5,
          8,
          10
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": false,
        "reference_images": false,
        "source_video": true,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.grok_video_extend",
      "object": "model",
      "capability": "video_generation",
      "name": "Grok Imagine Extend",
      "description": "Extend an existing video by 2–10s. Requires source_video_url.",
      "status": "available",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1"
        ],
        "duration_seconds": [
          2,
          5,
          10
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": false,
        "reference_images": false,
        "source_video": true,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "video.happy_horse",
      "object": "model",
      "capability": "video_generation",
      "name": "Happy Horse v1.1",
      "description": "Alibaba Happy Horse v1.1 — text/image/reference-to-video, plus video-edit.",
      "status": "preview",
      "is_default": false,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16",
          "1:1",
          "4:3",
          "3:4",
          "21:9",
          "9:21",
          "5:4",
          "4:5"
        ],
        "duration_seconds": [
          3,
          4,
          5,
          6,
          7,
          8,
          9,
          10,
          11,
          12,
          13,
          14,
          15
        ]
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": true,
        "source_video": true,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "speech.elevenlabs_turbo_v2_5",
      "object": "model",
      "capability": "speech_generation",
      "name": "ElevenLabs Turbo v2.5",
      "description": "Low-latency TTS, balance of quality and speed. Default.",
      "status": "available",
      "is_default": true,
      "limits": {
        "max_characters": 40000
      }
    },
    {
      "id": "speech.elevenlabs_flash_v2_5",
      "object": "model",
      "capability": "speech_generation",
      "name": "ElevenLabs Flash v2.5",
      "description": "Fastest ElevenLabs TTS, lowest cost.",
      "status": "available",
      "is_default": false,
      "limits": {
        "max_characters": 40000
      }
    },
    {
      "id": "speech.elevenlabs_v3",
      "object": "model",
      "capability": "speech_generation",
      "name": "ElevenLabs v3",
      "description": "Highest-quality expressive voice generation.",
      "status": "available",
      "is_default": false,
      "limits": {
        "max_characters": 40000
      }
    },
    {
      "id": "speech.elevenlabs_multilingual_v2",
      "object": "model",
      "capability": "speech_generation",
      "name": "ElevenLabs Multilingual v2",
      "description": "29 languages, high fidelity.",
      "status": "available",
      "is_default": false,
      "limits": {
        "max_characters": 40000
      }
    },
    {
      "id": "speech.seed_audio_1_0",
      "object": "model",
      "capability": "speech_generation",
      "name": "Seed Audio 1.0",
      "description": "ByteDance Seed Audio 1.0 — general text-to-audio: natural multilingual TTS plus full audio scenes (dialogue, ambience, radio dramas) from a prompt. voice_id is OPTIONAL and takes a Seed preset name (e.g. `vivi_mixed_en_zh_ja_es_id`, `mindy_en_es_id_pt_zh`, `kian_en_zh`, `sophie_en_zh`, `magnus_en_zh`) — NOT an ElevenLabs/cloned voice id; omit it to let the model narrate. Accepts up to 3 reference audio clips via audio_urls (reference them in the prompt as @Audio1–@Audio3) OR one reference image via image_url, plus speed/volume/pitch, output_format (wav|mp3|pcm|ogg_opus) and sample_rate. Billed per second (billed seconds ≈ ceil(text length / 15)).",
      "status": "available",
      "is_default": false,
      "limits": {
        "max_characters": 2048,
        "max_reference_audio": 3
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "music.elevenlabs_music_v1",
      "object": "model",
      "capability": "music_generation",
      "name": "ElevenLabs Music v1",
      "description": "Prompt-based music generation up to 10 minutes. Also accepts a `composition_plan` (MusicPrompt: positive/negative_global_styles + sections[] with lyrics lines) instead of a prompt for full structural control; `respect_sections_durations` controls how strictly section durations are enforced.",
      "status": "available",
      "is_default": true,
      "limits": {
        "max_duration_seconds": 600
      }
    },
    {
      "id": "music.elevenlabs_music_v2",
      "object": "model",
      "capability": "music_generation",
      "name": "ElevenLabs Music v2",
      "description": "ElevenLabs music_v2 — higher-quality music generation up to 10 minutes from a prompt, or a chunk-based `composition_plan` (chunks[] with text incl. [Section]/{direction} markup, duration_ms, positive/negative_styles, optional per-chunk audio conditioning refs + `seed`).",
      "status": "available",
      "is_default": false,
      "limits": {
        "max_duration_seconds": 600
      }
    },
    {
      "id": "music.lyria3_pro",
      "object": "model",
      "capability": "music_generation",
      "name": "Lyria 3 Pro",
      "description": "Google Lyria 3 Pro — full structured songs up to 3 minutes with vocals, lyrics, and multi-language support. Accepts an optional image_url for inspiration and a negative_prompt. Flat per-generation fee (duration is not configurable).",
      "status": "available",
      "is_default": false,
      "limits": {
        "max_duration_seconds": 180,
        "prompt_max_length": 5000
      },
      "capabilities": {
        "text_to_output": true,
        "image_to_output": true,
        "reference_images": false,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "sfx.elevenlabs_v1",
      "object": "model",
      "capability": "sound_effect_generation",
      "name": "ElevenLabs SFX",
      "description": "Sound effect generation up to 30s.",
      "status": "available",
      "is_default": true,
      "limits": {
        "max_duration_seconds": 30
      }
    },
    {
      "id": "transcription.whisper_v1",
      "object": "model",
      "capability": "transcription",
      "name": "OpenAI Whisper v1",
      "description": "Speech-to-text with word and segment timestamps. Accepts a direct audio/video URL or a YouTube URL. Async — returns a queued run; poll genfire_get_run for the transcript.",
      "status": "available",
      "is_default": true,
      "limits": {
        "max_file_mb": 500,
        "max_duration_seconds": 7200
      }
    },
    {
      "id": "image_edit.bria_background_remove",
      "object": "model",
      "capability": "image_editing",
      "name": "BRIA Background Remove",
      "description": "Remove the background from an image. Returns a transparent PNG.",
      "status": "available",
      "is_default": true,
      "limits": {
        "input": "image_url"
      }
    },
    {
      "id": "video_upscale.fal_video_upscaler",
      "object": "model",
      "capability": "video_upscaling",
      "name": "FAL Video Upscaler",
      "description": "Upscale a video by 2x or 4x. Async — returns a queued run; poll genfire_get_run for completion.",
      "status": "available",
      "is_default": true,
      "limits": {
        "scale_factors": [
          2,
          4
        ]
      }
    },
    {
      "id": "image_upscale.topaz_upscale_image",
      "object": "model",
      "capability": "image_upscaling",
      "name": "FAL Topaz Upscale",
      "description": "Upscale an image by 2x or 4x. Async — returns a queued run; poll genfire_get_run for completion.",
      "status": "available",
      "is_default": true,
      "limits": {
        "scale_factors": [
          2,
          4
        ]
      }
    },
    {
      "id": "lipsync.lipsync_2_pro",
      "object": "model",
      "capability": "lipsync_generation",
      "name": "Lipsync 2 Pro",
      "description": "High-quality lip-sync at 480p or 720p. Default.",
      "status": "available",
      "is_default": true,
      "limits": {
        "resolutions": [
          "480p",
          "720p"
        ]
      }
    },
    {
      "id": "lipsync.sync_lipsync_v2_pro",
      "object": "model",
      "capability": "lipsync_generation",
      "name": "Sync Lipsync v2 Pro",
      "description": "Alternative lip-sync engine.",
      "status": "available",
      "is_default": false,
      "limits": {
        "resolutions": [
          "480p",
          "720p"
        ]
      }
    },
    {
      "id": "lipsync.sync_lipsync_v3",
      "object": "model",
      "capability": "lipsync_generation",
      "name": "Sync Lipsync v3",
      "description": "Premium lip-sync engine — higher fidelity than v2 Pro.",
      "status": "available",
      "is_default": false,
      "limits": {
        "resolutions": [
          "480p",
          "720p"
        ]
      }
    },
    {
      "id": "3d.meshy_v6",
      "object": "model",
      "capability": "model_3d_generation",
      "name": "Meshy v6",
      "description": "Convert one image (or 1–4 images of the same object from different angles) into a textured 3D model. Outputs GLB/FBX/OBJ/USDZ/BLEND/STL plus optional PBR maps, auto-rigging, and animation. Game-ready — GLB loads natively in three.js / model-viewer. Async — returns a queued run; poll genfire_get_run for the model URLs. Processing takes 5–10 minutes.",
      "status": "available",
      "is_default": true,
      "limits": {
        "max_images": 4,
        "output_formats": [
          "glb",
          "fbx",
          "obj",
          "usdz",
          "blend",
          "stl"
        ],
        "target_polycount": {
          "min": 100,
          "max": 300000,
          "default": 30000
        },
        "topology": [
          "quad",
          "triangle"
        ]
      },
      "capabilities": {
        "text_to_output": false,
        "image_to_output": true,
        "reference_images": true,
        "source_video": false,
        "motion_control": false,
        "first_last_frame": false
      }
    },
    {
      "id": "game.genfire_v1",
      "object": "model",
      "capability": "game_generation",
      "name": "GenFire Games",
      "description": "Describe a game and get a fully-playable browser game (self-contained HTML, Phaser/canvas/Three.js). The completed run carries a public play_url you can open or share. Iterate by passing game_id with a change prompt. Async — returns a queued run; the codegen runs on a worker (usually 1–3 min). Poll GET /runs/{id} until status is completed, then read output.play_url.",
      "status": "available",
      "is_default": true,
      "limits": {
        "output": "playable_html",
        "shareable": true
      }
    },
    {
      "id": "app.genfire_v1",
      "object": "model",
      "capability": "app_generation",
      "name": "GenFire App Builder",
      "description": "Describe an app and get a working full-stack single-file web app (UI + in-browser data layer, hosted live). The completed run carries a public live_url you can open or share. Iterate by passing app_id with a change prompt. Async — returns a queued run; codegen runs on a worker (usually 1–3 min). Poll GET /runs/{id} until status is completed, then read output.live_url.",
      "status": "available",
      "is_default": true,
      "limits": {
        "output": "live_web_app",
        "shareable": true
      }
    },
    {
      "id": "reel.faceless",
      "object": "model",
      "capability": "faceless_reel_generation",
      "name": "Faceless Reel",
      "description": "End-to-end vertical (9:16) short: LLM script → voiceover → style-locked images → music → captioned video. Driven by a niche preset + visual style; cost varies with duration and music — call POST /v1/faceless-reels/estimate-cost for a per-config estimate.",
      "status": "available",
      "is_default": true,
      "limits": {
        "aspect_ratios": [
          "9:16"
        ],
        "target_duration_sec": {
          "min": 10,
          "max": 120,
          "default": null
        },
        "music_sources": [
          "none",
          "preset",
          "ai",
          "library"
        ],
        "catalogs": [
          "presets",
          "styles",
          "music-presets",
          "caption-presets"
        ]
      }
    },
    {
      "id": "explainer.omni",
      "object": "model",
      "capability": "explainer_generation",
      "name": "Explainer",
      "description": "Long-form narrated explainer/documentary (20s–10min, 16:9 or 9:16): script → expressive voiceover → style-locked frames → Gemini Omni Flash video clips → composed film with optional captions. Pass `script` (structured beats) to author the entire creative contract with YOUR OWN model — narration, per-scene shot-specs, motion notes, render modes, reference routing, emphasis words and recurring cast — and GenFire only renders; or pass just `topic` and GenFire writes the script. Cost varies with duration — call POST /v1/explainers/estimate-cost first.",
      "status": "available",
      "is_default": true,
      "limits": {
        "aspect_ratios": [
          "16:9",
          "9:16"
        ],
        "target_duration_sec": {
          "min": 20,
          "max": 600,
          "default": 60
        },
        "music_sources": [
          "none",
          "preset",
          "ai",
          "library"
        ],
        "script_beats": {
          "min": 3,
          "max": 100
        },
        "reference_images": {
          "max": 8
        },
        "cast_members": {
          "max": 3
        },
        "caption_modes": [
          "full",
          "keywords"
        ],
        "caption_positions": [
          "top",
          "middle",
          "bottom"
        ],
        "catalogs": [
          "styles"
        ]
      }
    }
  ]
}

GET /models/pricing

models:read

Get per-model base pricing

Returns the BASE credits per unit for every model. This is a base rate: the actual charge also scales with resolution, quality, duration, audio, count, and 3D add-ons. For the EXACT quote of a specific configuration, call POST /v1/models/estimate-cost.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/models/pricing \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "model": "image.nano_banana_2",
      "capability": "image_generation",
      "unit": "per_image",
      "credits": 7,
      "operation_key": "nano_banana_2"
    },
    {
      "model": "video.veo_3_1",
      "capability": "video_generation",
      "unit": "per_second",
      "credits": 30,
      "operation_key": "veo31_fast",
      "notes": "Base per-second rate. Resolution and count scale the cost — call POST /v1/models/estimate-cost for the exact quote. Audio adds a multiplier when generate_audio=true."
    },
    {
      "model": "video.seedance_2_0",
      "capability": "video_generation",
      "unit": "per_second",
      "credits": 30,
      "operation_key": "seedance_2_0",
      "notes": "Base (720p) per-second rate; 1080p ×2.25, 4K ×5.25. Call POST /v1/models/estimate-cost for the exact quote."
    },
    {
      "model": "speech.elevenlabs_turbo_v2_5",
      "capability": "speech_generation",
      "unit": "per_second",
      "credits": 1,
      "operation_key": "elevenlabs_tts_turbo_v2_5",
      "notes": "Billed seconds ≈ ceil(character_count / 15)."
    }
  ]
}

Notes

Unit values: `per_image` (image models, max 4 per request), `per_second` (video / speech / music / SFX / lipsync — speech bills seconds ≈ ceil(chars/15)), `per_generation` (flat, e.g. Lyria music and 3D mesh).
`credits` is a BASE rate. Video resolution multiplies it (e.g. Seedance 1080p ×2.25, 4K ×5.25); image 2K ×1.5 / 4K ×3 and GPT Image 2 quality ×6/×22; 3D texturing/PBR/rigging add-ons; audio-off discount on some video. Call POST /v1/models/estimate-cost for the exact number.

POST /models/estimate-cost

models:read

Estimate exact generation cost

Returns the EXACT credits a specific generation config will cost — accounting for resolution, quality, duration, audio, count, and 3D add-ons. Unlike GET /models/pricing (base rate), this equals what will actually be billed. Read-only; no idempotency key required.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

model string required

Model alias from GET /v1/models, e.g. video.seedance_2_0.

resolution string optional

Video/image resolution (e.g. 720p, 1080p, 4k, 2K).

duration number optional

Video duration in seconds (also used for lipsync audio when no audio_url).

generate_audio boolean optional

Whether audio is generated (affects some video models).

count number optional

Number of outputs (video/image).

quality string optional

Image quality tier (low/medium/high) — GPT Image 2 / GenFire.

should_texture boolean optional

3D: include base-color textures (default true).

enable_pbr boolean optional

3D: include PBR maps.

enable_rigging boolean optional

3D: include auto-rigging.

text string optional

Speech text (character_count derived from length).

character_count number optional

Speech character count (alternative to text).

duration_seconds number optional

Music / SFX duration in seconds.

audio_url string optional

Lipsync: audio URL (duration estimated when duration omitted).

curl Example

curl https://api.genfire.ai/v1/models/estimate-cost \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "video.seedance_2_0",
  "resolution": "1080p",
  "duration": 15,
  "generate_audio": true
}'

Response Example

{
  "object": "cost_estimate",
  "model": "video.seedance_2_0",
  "capability": "video_generation",
  "credits": 1013,
  "unit": "total",
  "breakdown": {
    "operation_key": "seedance_2_0",
    "base_rate": 30,
    "duration_seconds": 15,
    "resolution": "1080p",
    "resolution_multiplier": 2.25,
    "audio_multiplier": 1,
    "video_count": 1
  }
}

Request Example Body

{
  "model": "video.seedance_2_0",
  "resolution": "1080p",
  "duration": 15,
  "generate_audio": true
}

Notes

The returned `credits` is the exact charge for the given config — quote == charge.

GET /audio/voices

models:read

List voices for speech generation

Returns the voice ids accepted by `voice_id` on `/audio/speech`. By default this lists the voices you have cloned (their ids look like `fal_cloned_<id>`); a cloned voice id is otherwise only shown once at clone time in the dashboard, so this is the way to discover it programmatically. Pass `?include=stock` to also return built-in ElevenLabs stock voices.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

include query optional

Comma-separated extra sources to include. Currently only `stock` is supported, which appends built-in ElevenLabs voices.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/audio/voices \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "fal_cloned_abc123",
      "object": "voice",
      "name": "My Cloned Voice",
      "type": "cloned",
      "provider": "fal_qwen3",
      "preview_url": "https://cdn.genfire.ai/voice-clones/preview-abc123.wav",
      "created_at": "2026-05-01T12:00:00.000Z"
    }
  ]
}

Notes

Cloned voices are scoped to the authenticated account — you only ever see your own.
Stock voices are large and account-global, so they are excluded unless `include=stock` is passed.

Reference

Usage

GET /usage

runs:read

Get aggregated API usage

Aggregate API usage for the authenticated account over a date range. Returns totals (credits spent, run counts) plus a breakdown grouped by model, capability, or day. Default range is the last 30 days; max range is 365 days.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

start_date query optional

Inclusive lower bound (ISO date or full timestamp). Defaults to 30 days ago.

end_date query optional

Exclusive upper bound. Defaults to now.

group_by query optional

Bucketing for the breakdown: `model`, `capability`, `day`, or `none`.

Default: model

capability query optional

Optional filter, e.g. `video_generation`.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "usage_summary",
  "period": {
    "start": "2026-04-01T00:00:00.000Z",
    "end": "2026-04-30T23:59:59.999Z"
  },
  "group_by": "model",
  "totals": {
    "credits_spent": 4823,
    "runs_count": 187,
    "successful_runs": 178,
    "failed_runs": 9
  },
  "breakdown": [
    {
      "group": "video.veo_3_1",
      "credits_spent": 2400,
      "runs_count": 30,
      "successful_runs": 30,
      "failed_runs": 0,
      "avg_credits_per_run": 80
    },
    {
      "group": "image.nano_banana_2",
      "credits_spent": 423,
      "runs_count": 141,
      "successful_runs": 138,
      "failed_runs": 3,
      "avg_credits_per_run": 3
    }
  ]
}

Notes

Buckets are sorted by `credits_spent` descending, except `group_by=day` which is sorted chronologically.
Counts only include runs that hit `/v1` endpoints. Dashboard generations and workflow runs initiated outside the public API are not included.

Reference

Uploads

POST /uploads

uploads:write

Create a signed upload URL

Allocates a pre-signed PUT URL so a client can upload a local file directly to GenFire storage without proxying bytes through the API. Use the returned `asset_url` as `image_url`, `video_url`, or `audio_url` in subsequent generation requests.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

filename string required

Original filename. The extension is preserved in the stored object path.

content_type string optional

MIME type for the upload. Pinned into the signed URL — the PUT must send the same `Content-Type`.

Default: application/octet-stream

size_bytes number optional

Optional declared file size. Rejected if greater than the 5 GB ceiling.

curl Example

curl https://api.genfire.ai/v1/uploads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "reference.png",
  "content_type": "image/png",
  "size_bytes": 124000
}'

Response Example

{
  "asset_id": "asset_8f3c4a2b1d6e7f9a0b1c2d3e",
  "upload_url": "https://storage.googleapis.com/genfire-uploads/...?X-Goog-Signature=...",
  "asset_url": "https://storage.googleapis.com/genfire-uploads/...?X-Goog-Signature=...",
  "content_type": "image/png",
  "expires_at": "2026-05-12T02:21:25.985Z"
}

Request Example Body

{
  "filename": "reference.png",
  "content_type": "image/png",
  "size_bytes": 124000
}

Notes

PUT the file bytes to `upload_url` within 15 minutes. The signed URL is pinned to the `content_type` you submitted — sending a different `Content-Type` header will be rejected by the storage layer.
`asset_url` is a 7-day signed READ URL. Re-upload the asset before this point if you need long-lived references.
Maximum upload size is 5 GB.

Reference

Influencers

GET /influencers

influencers:read

List your trained influencers

Returns the influencer characters owned by the authenticated account that are in `ready` status. Use the returned `id` and `handle` in the `mentions` array of an image generation request to inject the character.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/influencers \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "model_abc123def456",
      "object": "influencer",
      "handle": "sarah",
      "display_name": "Sarah Chen",
      "status": "ready",
      "source_type": "uploaded",
      "preview_url": "https://firebasestorage.googleapis.com/...",
      "created_at": "2026-04-12T10:30:00.000Z",
      "updated_at": "2026-04-12T10:35:00.000Z"
    }
  ]
}

Notes

Drafts and archived influencers are NOT returned. Train and finalize them in the dashboard before they can be referenced.

GET /influencers/{influencerId}

influencers:read

Get a single influencer by id

Returns full details for one influencer the authenticated account owns.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

influencerId path required

Influencer id from `GET /v1/influencers`.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/influencers/{influencerId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "id": "model_abc123def456",
  "object": "influencer",
  "handle": "sarah",
  "display_name": "Sarah Chen",
  "status": "ready",
  "source_type": "uploaded",
  "preview_url": "https://firebasestorage.googleapis.com/...",
  "created_at": "2026-04-12T10:30:00.000Z",
  "updated_at": "2026-04-12T10:35:00.000Z"
}

Notes

404 if the influencer does not exist or is not owned by the authenticated account.

POST /influencers

influencers:write

Create an influencer (from photos or from scratch)

Creates a reusable influencer character in one of two modes: 1. **From photos** — supply `photo_urls` (1–8 reference photos of a real person). The bytes are copied into durable storage and a 4-panel character reference sheet is generated to lock the identity. 2. **From scratch** — supply `appearance` (no photos). A brand-new person is generated from the described traits: first a hero photo, then the reference sheet from it. Provide exactly one of `photo_urls` or `appearance`. The call returns immediately with `status: "creating"`; the generation runs asynchronously (~30–90s). Poll `GET /v1/influencers/{id}` until `status` is `ready` (or `failed`). Billable: sheet (and, for from-scratch, hero) generation charges credits.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

handle string required

Short @-mention handle (letters, digits, underscores), e.g. `maya`. Lowercased automatically. Must be unique within your account. This is the influencer's only name — the `display_name` in responses is derived from it.

photo_urls string[] optional

FROM-PHOTOS mode. 1–8 absolute https URLs of reference photos. Upload local files via `POST /v1/uploads` first and pass the returned `asset_url`s here. Mutually exclusive with `appearance`.

appearance object optional

FROM-SCRATCH mode. Generate a new person from traits. Fields: `gender` (string, required — e.g. "woman", "man"), `heritage` (string, required — race/ethnicity, e.g. "korean"), `age` (string, required — one of `18-21`, `21-25`, `25-30`, `30-40`, `40+`), `prompt` (string, optional — free-text descriptor, e.g. "freckles, platinum bob, green eyes, editorial look"). Mutually exclusive with `photo_urls`.

curl Example

curl https://api.genfire.ai/v1/influencers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "handle": "maya",
  "appearance": {
    "gender": "woman",
    "heritage": "korean",
    "age": "21-25",
    "prompt": "freckles, platinum blonde bob, green eyes, editorial fashion look"
  }
}'

Response Example

{
  "id": "model_abc123def456",
  "object": "influencer",
  "handle": "maya",
  "display_name": "Maya",
  "status": "creating",
  "source_type": "generated",
  "preview_url": null,
  "created_at": "2026-06-18T10:30:00.000Z",
  "updated_at": "2026-06-18T10:30:00.000Z"
}

Request Example Body

{
  "handle": "maya",
  "appearance": {
    "gender": "woman",
    "heritage": "korean",
    "age": "21-25",
    "prompt": "freckles, platinum blonde bob, green eyes, editorial fashion look"
  }
}

Notes

Requires the `influencers:write` scope and an `Idempotency-Key` header.
Provide exactly one of `photo_urls` (clone from photos) or `appearance` (generate from scratch).
Asynchronous: the response is `status: "creating"`. Poll `GET /v1/influencers/{id}` until `ready`.
Billable: generating the reference sheet (and, for from-scratch, the hero photo) charges credits against your account.
Once `ready`, reference the influencer in image generation via the `mentions` array using the returned `id` and `handle`.

Reference

Elements

GET /elements

elements:read

List your reusable image elements

Returns the named image "elements" (reusable props — a product, logo, object) owned by the authenticated account. Reference an element in a video prompt by writing `@<handle>`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/elements \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "elem_abc123",
      "object": "element",
      "handle": "redbottle",
      "name": "Red Bottle",
      "image_url": "https://firebasestorage.googleapis.com/...",
      "thumbnail_url": "https://firebasestorage.googleapis.com/...",
      "source_type": "upload",
      "aspect_ratio": "1:1",
      "created_at": "2026-06-29T10:30:00.000Z",
      "updated_at": "2026-06-29T10:30:00.000Z"
    }
  ]
}

Notes

Element `@<handle>` mentions resolve only on reference-capable video models (Seedance, Veo 3.1 reference, Grok reference). They are ignored by image models and by Kling/Happy Horse.

GET /elements/{elementId}

elements:read

Get a single element by id

Returns full details for one element the authenticated account owns.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

elementId path required

Element id from `GET /v1/elements`.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/elements/{elementId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "id": "elem_abc123",
  "object": "element",
  "handle": "redbottle",
  "name": "Red Bottle",
  "image_url": "https://firebasestorage.googleapis.com/...",
  "thumbnail_url": "https://firebasestorage.googleapis.com/...",
  "source_type": "upload",
  "aspect_ratio": "1:1",
  "created_at": "2026-06-29T10:30:00.000Z",
  "updated_at": "2026-06-29T10:30:00.000Z"
}

Notes

404 if the element does not exist or is not owned by the authenticated account.

POST /elements

elements:write

Create an element from an image

Creates a reusable named image element from a single image URL. Synchronous and free (no generation): the element is returned immediately in `ready` status. Once created, write `@<handle>` in a video generation `prompt` to drop the element image into the scene on reference-capable models.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

name string required

Human-friendly name, e.g. `Red Bottle`. Also used as the in-prompt phrase ("the Red Bottle") when the `@handle` is resolved.

image_url string required

Absolute https URL of the element image. Upload a local file via `POST /v1/uploads` first and pass the returned `asset_url`.

handle string optional

Short @-mention handle (letters, digits, underscores), e.g. `redbottle`. Lowercased automatically. Auto-derived from `name` if omitted. Must be unique within your account.

aspect_ratio string optional

Optional aspect ratio of the image, e.g. `1:1`, `9:16`. Informational only.

curl Example

curl https://api.genfire.ai/v1/elements \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Red Bottle",
  "handle": "redbottle",
  "image_url": "https://storage.googleapis.com/.../bottle.png"
}'

Response Example

{
  "id": "elem_abc123",
  "object": "element",
  "handle": "redbottle",
  "name": "Red Bottle",
  "image_url": "https://firebasestorage.googleapis.com/...",
  "thumbnail_url": "https://firebasestorage.googleapis.com/...",
  "source_type": "upload",
  "aspect_ratio": "1:1",
  "created_at": "2026-06-29T10:30:00.000Z",
  "updated_at": "2026-06-29T10:30:00.000Z"
}

Request Example Body

{
  "name": "Red Bottle",
  "handle": "redbottle",
  "image_url": "https://storage.googleapis.com/.../bottle.png"
}

Notes

Requires the `elements:write` scope.
Not billable — no generation runs; the supplied image URL is stored as the element.
To use: write `@<handle>` in a `POST /v1/videos/generations` prompt on a reference-capable model (Seedance, Veo 3.1 reference, or Grok reference).

DELETE /elements/{elementId}

elements:write

Delete an element

Removes an element from your library. The underlying image is not affected; only the named `@handle` reference is deleted.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

elementId path required

Element id from `GET /v1/elements`.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/elements/{elementId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "id": "elem_abc123",
  "object": "element",
  "deleted": true
}

Notes

404 if the element does not exist or is not owned by the authenticated account.

Reference

Games

POST /games/generations

images:write

Generate a browser game

Build a fully-playable, self-contained HTML browser game (Phaser / canvas / Three.js) from a text prompt. The generated game is hosted automatically; once the run completes its `play_url` is public and anyone can open it — no install. Iterate on an existing game by passing its `game_id` with a change prompt. Async — returns a queued run immediately and the codegen runs on a worker (usually 1–3 min); poll `GET /runs/{id}` until `status` is `completed`, then read `output.play_url`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

prompt string required

What game to build — or, with `game_id`, the change to make (e.g. "make it faster, add a boss").

game_id string optional

Iterate on an existing game: pass the `game_id` from a prior generation. The stored game is re-generated in place at the same `play_url`.

model string optional

Codegen model alias (e.g. `claude-opus-4-8`, `claude-sonnet-4-6`). Defaults to Opus.

asset_urls array optional

Up to 16 asset URLs (images / GLB / audio from other GenFire endpoints) to wire into the game as sprites, textures, or sound.

multiplayer boolean optional

Build with realtime multiplayer via the GenFire relay. Players join with the same `?room=` link.

Default: false

curl Example

curl https://api.genfire.ai/v1/games/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "A neon endless-runner where you dodge obstacles and collect coins",
  "multiplayer": false
}'

Response Example

{
  "id": "run_game_123",
  "object": "run",
  "status": "queued",
  "capability": "game_generation",
  "endpoint": "games.generations.create",
  "model": "game.genfire_v1",
  "request_id": "run_game_123",
  "input_summary": {
    "prompt": "A neon endless-runner where you dodge obstacles and collect coins",
    "iterate": false
  },
  "output": null,
  "usage": null,
  "error": null,
  "resource_id": "game_123",
  "provider_request_id": null,
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:00.000Z",
  "completed_at": null
}

Request Example Body

{
  "prompt": "A neon endless-runner where you dodge obstacles and collect coins",
  "multiplayer": false
}

Notes

Guarded by `images:write` — game generation also produces a cover thumbnail via image generation.
Async: the POST returns a `queued` run with `output: null`. Poll `GET /runs/{id}` until `status` is `completed`; the run output then contains `game_id`, `play_url`, `thumbnail_url`, and `title`. The `play_url` is shareable as soon as it appears; use `POST /games/{gameId}/publish` to also list it in the public gallery.

POST /games/{gameId}/publish

images:write

Publish or unpublish a game

Publish a completed game you own to the public GenFire games gallery (genfire.ai/games), where anyone can discover and play it. Pass `{ "publish": false }` to remove it from the gallery again. The game's `play_url` is shareable whether or not it is published — publishing only controls the public marketplace listing.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

gameId path required

The `game_id` of a completed game from `POST /games/generations`.

Body Fields

publish boolean optional

true (default) to publish to the public gallery; false to unpublish.

Default: true

curl Example

curl https://api.genfire.ai/v1/games/{gameId}/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "publish": true
}'

Response Example

{
  "id": "game_abc123",
  "object": "game",
  "is_public": true
}

Request Example Body

{
  "publish": true
}

Notes

Returns 404 if the game does not exist, is not owned by the authenticated account, or is not in a completed state.

Reference

Runs

GET /runs

runs:read

List recent runs

Lists recent runs for the authenticated account. Use this to inspect async activity across generation endpoints and workflows.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

status query optional

Optional run status filter such as `queued`, `processing`, `completed`, or `failed`.

capability query optional

Optional capability filter such as `image_generation` or `workflow.hook_pack`.

limit query optional

Maximum number of runs to return.

Default: 25

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/runs \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "run_img_123",
      "object": "run",
      "status": "completed",
      "capability": "image_generation",
      "endpoint": "images.generations.create",
      "model": "image.nano_banana_2",
      "request_id": "run_img_123",
      "input_summary": {
        "prompt": "Studio product photo of a matte black water bottle",
        "model": "image.nano_banana_2",
        "aspect_ratio": "1:1",
        "count": 1
      },
      "output": {
        "images": [
          {
            "url": "https://cdn.genfire.ai/output/image-001.png"
          }
        ],
        "output_url": "https://cdn.genfire.ai/output/image-001.png"
      },
      "usage": {
        "credits": 8
      },
      "error": null,
      "resource_id": null,
      "provider_request_id": null,
      "created_at": "2026-03-25T12:00:00.000Z",
      "updated_at": "2026-03-25T12:00:02.000Z",
      "completed_at": "2026-03-25T12:00:02.000Z"
    },
    {
      "id": "run_vid_123",
      "object": "run",
      "status": "queued",
      "capability": "video_generation",
      "endpoint": "videos.generations.create",
      "model": "video.veo_3_1",
      "request_id": "run_vid_123",
      "input_summary": {
        "prompt": "Cinematic close-up of a luxury watch with soft lighting",
        "model": "video.veo_3_1",
        "aspect_ratio": "16:9",
        "duration": 8,
        "has_image": false,
        "generate_audio": true
      },
      "output": null,
      "usage": null,
      "error": null,
      "resource_id": "video_123",
      "provider_request_id": "provider_req_123",
      "created_at": "2026-03-25T12:00:00.000Z",
      "updated_at": "2026-03-25T12:00:00.000Z",
      "completed_at": null
    }
  ]
}

GET /runs/{runId}

runs:read

Get a run by id

Use the run id returned by a generation endpoint or workflow execution to inspect status, output, usage, and provider metadata.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

runId path required

The run id returned by the API.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/runs/{runId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "id": "run_img_123",
  "object": "run",
  "status": "completed",
  "capability": "image_generation",
  "endpoint": "images.generations.create",
  "model": "image.nano_banana_2",
  "request_id": "run_img_123",
  "input_summary": {
    "prompt": "Studio product photo of a matte black water bottle",
    "model": "image.nano_banana_2",
    "aspect_ratio": "1:1",
    "count": 1
  },
  "output": {
    "images": [
      {
        "url": "https://cdn.genfire.ai/output/image-001.png"
      }
    ],
    "output_url": "https://cdn.genfire.ai/output/image-001.png"
  },
  "usage": {
    "credits": 8
  },
  "error": null,
  "resource_id": null,
  "provider_request_id": null,
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:02.000Z",
  "completed_at": "2026-03-25T12:00:02.000Z"
}

GET /runs/{runId}/output

runs:read

Get the output envelope for a run

Returns just the terminal output envelope for a run, which is useful when you only need the final payload.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

runId path required

The run id returned by the API.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/runs/{runId}/output \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "id": "run_img_123",
  "object": "run_output",
  "status": "completed",
  "capability": "image_generation",
  "output": {
    "images": [
      {
        "url": "https://cdn.genfire.ai/output/image-001.png"
      }
    ],
    "output_url": "https://cdn.genfire.ai/output/image-001.png"
  },
  "error": null,
  "completed_at": "2026-03-25T12:00:02.000Z"
}

Reference

Generation

POST /images/generations

images:write

Generate images

Create one or more images using a public image model alias. This endpoint usually completes synchronously and returns a completed run.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

prompt string required

The image prompt. May include @<handle> mentions when paired with a `mentions` array.

model string optional

Optional image model alias from `/models`. Models with an internal edit variant accept `mentions`, `image_url`, and `image_urls` for influencer-conditioned or multi-image edits.

Default: image.nano_banana_2

aspect_ratio string optional

Image aspect ratio.

Default: 1:1

count integer optional

Number of images to generate, from 1 to 4.

Default: 1

image_url string optional

Optional single source image URL. When provided with an edit-capable model, the request is routed through the model's edit variant. Use `image_urls` for multi-image edits.

image_urls array optional

Optional list of up to 14 source image URLs for a multi-image edit. Supported by GPT Image 2, Seedream, Qwen Image 2 and Nano Banana; Grok uses at most the first 3. Routes through the model's edit variant.

mentions array optional

Optional `[{ handle, influencer_id }]` to inject a trained influencer character into the image. The model is auto-switched to its edit variant and the influencer's reference photos are added as conditioning. Currently a single mention per request is supported.

quality string optional

Quality tier: low, medium, high, auto. Only applies to image.gpt_image_2. Affects cost: low=1×, medium=6×, high=22×.

Default: medium

resolution string optional

Output resolution: 1K, 2K, 4K. Nano Banana family edit only (image.nano_banana, image.nano_banana_2, image.nano_banana_pro) — request must supply image_url or mentions to route through the model edit variant. Affects cost: 1K=1×, 2K=1.5×, 4K=3×.

curl Example

curl https://api.genfire.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Studio product photo of a matte black water bottle on dark stone",
  "model": "image.nano_banana_2",
  "aspect_ratio": "1:1",
  "count": 1
}'

Response Example

{
  "id": "run_img_123",
  "object": "run",
  "status": "completed",
  "capability": "image_generation",
  "endpoint": "images.generations.create",
  "model": "image.nano_banana_2",
  "request_id": "run_img_123",
  "input_summary": {
    "prompt": "Studio product photo of a matte black water bottle",
    "model": "image.nano_banana_2",
    "aspect_ratio": "1:1",
    "count": 1
  },
  "output": {
    "images": [
      {
        "url": "https://cdn.genfire.ai/output/image-001.png"
      }
    ],
    "output_url": "https://cdn.genfire.ai/output/image-001.png"
  },
  "usage": {
    "credits": 8
  },
  "error": null,
  "resource_id": null,
  "provider_request_id": null,
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:02.000Z",
  "completed_at": "2026-03-25T12:00:02.000Z"
}

Request Example Body

{
  "prompt": "Studio product photo of a matte black water bottle on dark stone",
  "model": "image.nano_banana_2",
  "aspect_ratio": "1:1",
  "count": 1
}

Notes

When `mentions` is supplied: the model must have an internal edit variant (most do — see `/models`). The server resolves the influencer, replaces `@<handle>` in the prompt with `the character`, appends an identity directive, and adds up to four reference images as conditioning.
Influencers must be in status `ready`. Drafts and archived ones cannot be referenced.

POST /videos/generations

videos:write

Generate videos

Create a video run. Routing is automatic from the inputs you supply: prompt only → text-to-video, +image_url → image-to-video, +reference_image_urls → reference-to-video, +source_video_url → video-edit/extend, +image_url +source_video_url → motion-control, +first_frame_url +last_frame_url → first-last-frame interpolation. Each video model declares which combinations it supports under `capabilities` on `GET /models`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

prompt string required

The video prompt.

model string optional

Optional video model alias from `/models`.

Default: video.veo_3_1

aspect_ratio string optional

Video aspect ratio.

Default: 16:9

duration integer optional

Target duration in seconds.

Default: 5

resolution string optional

Output resolution (e.g. 480p, 720p, 1080p, 4k). Supported values and pricing are per-model — see `resolutions` under `/models`. Higher resolutions cost more credits.

image_url string optional

Source image for image-to-video, or character image for motion-control.

source_video_url string optional

Source video for video-edit, video-extend, or motion-control modes.

reference_image_urls array optional

Up to 9 reference image URLs for reference-to-video mode.

first_frame_url string optional

First-frame image for first-last-frame interpolation. Must be paired with last_frame_url.

last_frame_url string optional

Last-frame image for first-last-frame interpolation. Must be paired with first_frame_url.

generate_audio boolean optional

Whether to include generated audio when supported.

Default: true

bitrate_mode string optional

Output encoding bitrate for Seedance 2.0: `standard` or `high`. `high` requests a larger, higher-quality encode at no extra credit cost.

Default: standard

elements array optional

Kling O3 only. Up to 3 structured elements (characters/objects), referenced in the prompt as `@Element1`, `@Element2`, `@Element3`. Passing elements selects the reference-to-video endpoint. Each element is an object: `{ frontal_image_url: string (main view), reference_image_urls?: string[] (1–3 extra angles), video_url?: string (a 3–10s driving clip — at most ONE element may carry a video), voice_id?: string (from POST /videos/voices) }`. Each element must have a frontal_image_url OR a video_url.

multi_prompt array optional

Kling O3 only. Multi-shot sequence: an array of `{ prompt: string, duration?: string ("1"–"15" seconds) }`. When provided it replaces the top-level `prompt` for shot structure.

shot_type string optional

Kling O3 only. Multi-shot structure: `customize` (you define shots) or `intelligent` (the model decides). Default `customize`.

start_image_url string optional

Kling O3 reference-to-video only. Image to use as the first frame of the generated video.

end_image_url string optional

Kling O3 reference-to-video only. Image to use as the last frame of the generated video.

curl Example

curl https://api.genfire.ai/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Cinematic close-up of a luxury watch with soft lighting",
  "model": "video.veo_3_1",
  "aspect_ratio": "16:9",
  "duration": 8,
  "generate_audio": true
}'

Response Example

{
  "id": "run_vid_123",
  "object": "run",
  "status": "queued",
  "capability": "video_generation",
  "endpoint": "videos.generations.create",
  "model": "video.veo_3_1",
  "request_id": "run_vid_123",
  "input_summary": {
    "prompt": "Cinematic close-up of a luxury watch with soft lighting",
    "model": "video.veo_3_1",
    "aspect_ratio": "16:9",
    "duration": 8,
    "has_image": false,
    "generate_audio": true
  },
  "output": null,
  "usage": null,
  "error": null,
  "resource_id": "video_123",
  "provider_request_id": "provider_req_123",
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:00.000Z",
  "completed_at": null
}

Request Example Body

{
  "prompt": "Cinematic close-up of a luxury watch with soft lighting",
  "model": "video.veo_3_1",
  "aspect_ratio": "16:9",
  "duration": 8,
  "generate_audio": true
}

Notes

Poll `GET /runs/{runId}` until the run moves to `completed` or `failed`.
Per-model duration / aspect-ratio / resolution limits are returned by `/models`; passing an unsupported value returns a 400 listing the allowed values.
If you provide an input combination the model does not declare in `capabilities`, you get `unsupported_input_combination`.
The structured fields `elements`, `multi_prompt`, `shot_type`, `start_image_url`, and `end_image_url` apply to Kling O3 models only (`video.kling_o3`, `video.kling_o3_pro`, `video.kling_o3_4k`) and are ignored by every other model. Create a Kling `voice_id` for an element with POST `/videos/voices`.
Kling O3 Standard/Pro also support video-to-video reference: pass `source_video_url` together with `reference_image_urls` (or `elements`) to restyle a source clip while binding reference characters.

POST /videos/voices

videos:write

Create a Kling voice

Register a custom Kling voice from a short audio/video sample (5–30s, clean single-voice `.mp3/.wav/.mp4/.mov`). Returns a `voice_id` that can be bound to a Kling O3 element (`elements[].voice_id`) on POST `/videos/generations` so that element speaks in the cloned voice. Synchronous. This is Kling's own voice registry — the id is only meaningful to Kling video models.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

voice_url string required

URL of the voice sample. `.mp3/.wav` audio or `.mp4/.mov` video, 5–30 seconds, clean single-voice audio.

curl Example

curl https://api.genfire.ai/v1/videos/voices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "voice_url": "https://example.com/voice-sample.mp3"
}'

Response Example

{
  "voice_id": "kling_voice_abc123"
}

Request Example Body

{
  "voice_url": "https://example.com/voice-sample.mp3"
}

Notes

Bind the returned `voice_id` to an element: `elements: [{ frontal_image_url: "…", voice_id: "kling_voice_abc123" }]` on POST `/videos/generations` with a Kling O3 model.

POST /images/background-remove

images:write

Remove image background

Remove the background from an image using BRIA. Returns a transparent PNG. Synchronous — typically completes in a couple seconds.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

image_url string required

Absolute URL of the source image.

curl Example

curl https://api.genfire.ai/v1/images/background-remove \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "image_url": "https://example.com/photo.jpg"
}'

Response Example

{
  "id": "run_bg_123",
  "object": "run",
  "status": "completed",
  "capability": "image_editing",
  "endpoint": "images.background_remove.create",
  "model": "image_edit.bria_background_remove",
  "request_id": "run_bg_123",
  "input_summary": {
    "model": "image_edit.bria_background_remove",
    "image_url": "https://example.com/photo.jpg"
  },
  "output": {
    "images": [
      {
        "url": "https://cdn.genfire.ai/output/bg-removed.png"
      }
    ],
    "output_url": "https://cdn.genfire.ai/output/bg-removed.png"
  },
  "usage": {
    "credits": 1
  },
  "error": null,
  "resource_id": null,
  "provider_request_id": null,
  "created_at": "2026-04-30T12:00:00.000Z",
  "updated_at": "2026-04-30T12:00:01.500Z",
  "completed_at": "2026-04-30T12:00:01.500Z"
}

Request Example Body

{
  "image_url": "https://example.com/photo.jpg"
}

POST /videos/upscale

videos:write

Upscale a video

Upscale a video by 2x or 4x using FAL's video upscaler. Async — returns a queued run; poll `/runs/{runId}` for completion (typically 1-5 min).

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

source_video_url string required

Absolute URL of the source video.

scale_factor integer optional

Either 2 or 4.

Default: 2

curl Example

curl https://api.genfire.ai/v1/videos/upscale \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "source_video_url": "https://cdn.genfire.ai/video.mp4",
  "scale_factor": 2
}'

Response Example

{
  "id": "run_upscale_123",
  "object": "run",
  "status": "queued",
  "capability": "video_upscaling",
  "endpoint": "videos.upscale.create",
  "model": "video_upscale.fal_video_upscaler",
  "request_id": "run_upscale_123",
  "input_summary": {
    "model": "video_upscale.fal_video_upscaler",
    "scale_factor": 2
  },
  "output": null,
  "usage": null,
  "error": null,
  "resource_id": null,
  "provider_request_id": "fal_req_abc",
  "created_at": "2026-04-30T12:00:00.000Z",
  "updated_at": "2026-04-30T12:00:00.500Z",
  "completed_at": null
}

Request Example Body

{
  "source_video_url": "https://cdn.genfire.ai/video.mp4",
  "scale_factor": 2
}

Notes

Costs more credits than generation per-second, scaled by the scale factor.
Poll `GET /runs/{runId}` until status is `completed` or `failed`.

POST /images/upscale

images:write

Upscale an image

Upscale an image by 2x or 4x using FAL's Topaz upscaler. Async — returns a queued run; poll `/runs/{runId}` for completion (typically 1-2 min).

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

source_image_url string required

Absolute URL of the source image.

scale_factor integer optional

Either 2 or 4.

Default: 2

curl Example

curl https://api.genfire.ai/v1/images/upscale \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "source_image_url": "https://cdn.genfire.ai/image.png",
  "scale_factor": 2
}'

Response Example

{
  "id": "run_img_upscale_123",
  "object": "run",
  "status": "queued",
  "capability": "image_upscaling",
  "endpoint": "images.upscale.create",
  "model": "image_upscale.topaz_upscale_image",
  "request_id": "run_img_upscale_123",
  "input_summary": {
    "model": "image_upscale.topaz_upscale_image",
    "scale_factor": 2
  },
  "output": null,
  "usage": null,
  "error": null,
  "resource_id": null,
  "provider_request_id": "fal_req_def",
  "created_at": "2026-04-30T12:00:00.000Z",
  "updated_at": "2026-04-30T12:00:00.500Z",
  "completed_at": null
}

Request Example Body

{
  "source_image_url": "https://cdn.genfire.ai/image.png",
  "scale_factor": 2
}

Notes

Costs scale with the scale factor (4x costs more than 2x).
Poll `GET /runs/{runId}` until status is `completed` or `failed`.

POST /lipsync/generations

lipsync:write

Generate a lip-synced video

Lip-sync an existing video to either a hosted audio file or a base64-encoded audio payload.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

video_url string required

Absolute URL to the source video.

audio_url string optional

Absolute URL to the source audio.

audio_base64 string optional

Base64-encoded audio content. Provide this instead of `audio_url` when uploading audio inline.

audio_file_name string optional

Optional file name to associate with inline audio.

title string optional

Optional title used for the internal video record.

Default: AI Lip-sync Video

description string optional

Optional description for the internal video record.

sync_mode string optional

How the video should align to the audio.

Default: cut_off

model string optional

Optional lipsync model alias from `/models`.

Default: lipsync.lipsync_2_pro

duration number optional

Optional duration hint between 1 and 300 seconds.

curl Example

curl https://api.genfire.ai/v1/lipsync/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "video_url": "https://example.com/source-video.mp4",
  "audio_url": "https://example.com/source-audio.mp3",
  "sync_mode": "cut_off",
  "model": "lipsync.lipsync_2_pro"
}'

Response Example

{
  "id": "run_vid_123",
  "object": "run",
  "status": "queued",
  "capability": "lipsync_generation",
  "endpoint": "lipsync.generations.create",
  "model": "lipsync.lipsync_2_pro",
  "request_id": "run_vid_123",
  "input_summary": {
    "prompt": "Cinematic close-up of a luxury watch with soft lighting",
    "model": "video.veo_3_1",
    "aspect_ratio": "16:9",
    "duration": 8,
    "has_image": false,
    "generate_audio": true
  },
  "output": null,
  "usage": null,
  "error": null,
  "resource_id": "video_123",
  "provider_request_id": "provider_req_123",
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:00.000Z",
  "completed_at": null
}

Request Example Body

{
  "video_url": "https://example.com/source-video.mp4",
  "audio_url": "https://example.com/source-audio.mp3",
  "sync_mode": "cut_off",
  "model": "lipsync.lipsync_2_pro"
}

Notes

Provide either `audio_url` or `audio_base64`.
This endpoint is async and usually returns a queued run first.

POST /audio/speech

audio:write

Generate speech audio

Text-to-speech generation using a public speech model alias.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

text string required

The text to speak. For `speech.seed_audio_1_0` this is a free-form audio prompt (max 2048 chars) that can also describe scenes/dialogue and reference audio inputs as @Audio1–@Audio3.

voice_id string optional

The voice id to use: either a stock ElevenLabs voice id or one of your cloned voice ids (`fal_cloned_<id>`). List options via `/audio/voices`. Required for ElevenLabs models. For `speech.seed_audio_1_0` it is OPTIONAL and takes a Seed preset name (e.g. `vivi_mixed_en_zh_ja_es_id`) instead.

model string optional

Optional speech model alias from `/models`.

Default: speech.elevenlabs_turbo_v2_5

voice_name string optional

Optional human-readable voice name passed through to the audio generator.

output_format string optional

Optional output format when supported by the backing provider. For `speech.seed_audio_1_0`: one of `wav`, `mp3`, `pcm`, `ogg_opus` (default `mp3`).

audio_urls string[] optional

Seed Audio 1.0 only — up to 3 reference audio URLs (each ≤30s / 10MB), referenced in the prompt as @Audio1–@Audio3. Cannot be combined with `image_url`.

image_url string optional

Seed Audio 1.0 only — a single reference image URL (jpeg/png/webp ≤10MB). Cannot be combined with `audio_urls`.

sample_rate number optional

Seed Audio 1.0 only — output sample rate in Hz: 8000, 16000, 24000 (default), 32000, 44100 or 48000.

speed number optional

Seed Audio 1.0 only — speech speed 0.5–2 (1 = normal).

volume number optional

Seed Audio 1.0 only — volume 0.5–2 (1 = normal).

pitch number optional

Seed Audio 1.0 only — pitch shift in semitones, -12 to 12 (0 = normal).

curl Example

curl https://api.genfire.ai/v1/audio/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Introducing the new GenFire creative workflow.",
  "voice_id": "voice_abc123",
  "model": "speech.elevenlabs_turbo_v2_5"
}'

Response Example

{
  "id": "run_speech_123",
  "object": "run",
  "status": "completed",
  "capability": "speech_generation",
  "endpoint": "audio.speech.create",
  "model": "speech.elevenlabs_turbo_v2_5",
  "request_id": "run_img_123",
  "input_summary": {
    "prompt": "Studio product photo of a matte black water bottle",
    "model": "image.nano_banana_2",
    "aspect_ratio": "1:1",
    "count": 1
  },
  "output": {
    "audio_id": "audio_123",
    "audio_url": "https://cdn.genfire.ai/output/audio-123.mp3",
    "duration": 6.4
  },
  "usage": {
    "credits": 8
  },
  "error": null,
  "resource_id": null,
  "provider_request_id": null,
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:02.000Z",
  "completed_at": "2026-03-25T12:00:02.000Z"
}

Request Example Body

{
  "text": "Introducing the new GenFire creative workflow.",
  "voice_id": "voice_abc123",
  "model": "speech.elevenlabs_turbo_v2_5"
}

POST /audio/music

audio:write

Generate music

Create music from a prompt or a structured composition plan. You can request a simple audio result or a more detailed music result with timestamps.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

prompt string optional

Description of the music you want generated. Required unless `composition_plan` is provided; the two cannot be combined.

composition_plan object optional

Structured composition plan instead of a prompt (ElevenLabs only). music_v1 shape: `{ positive_global_styles[], negative_global_styles[], sections[] }` with per-section styles, duration_ms (3000-120000) and lyric lines. music_v2 shape: `{ chunks[] }` where each chunk has `text` (may carry [Section] and {direction} markup), `duration_ms`, `positive_styles[]` and optional audio-conditioning refs. Duration and billing derive from the plan's summed durations.

model string optional

Optional music model alias from `/models`. A chunks-shaped `composition_plan` implies `music.elevenlabs_music_v2`.

Default: music.elevenlabs_music_v1

duration_seconds number optional

Desired music length in seconds, 3-600 (ElevenLabs prompt mode only — ignored with `composition_plan`, and by Lyria 3 Pro which produces a flat-length song).

Default: 30

include_details boolean optional

Return detailed music metadata when supported (ElevenLabs only).

Default: false

with_timestamps boolean optional

Include timestamps when `include_details` is true (ElevenLabs only).

Default: false

force_instrumental boolean optional

Guarantee instrumental output (ElevenLabs prompt mode only).

respect_sections_durations boolean optional

With a music_v1 `composition_plan`: enforce section durations exactly instead of letting the model flex them (music_v2 always enforces them).

Default: true

seed integer optional

Random seed for more consistent results (ElevenLabs `composition_plan` mode only).

image_url string optional

Optional image URL used as inspiration for the generated music. Lyria 3 Pro only — the model matches the mood and theme of the image.

negative_prompt string optional

Description of what to exclude from the generated audio. Lyria 3 Pro only.

output_format string optional

Optional output format when supported by the backing provider (ElevenLabs default `auto` picks the best mp3 for the model).

curl Example

curl https://api.genfire.ai/v1/audio/music \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Confident electronic music bed for a product launch video",
  "model": "music.elevenlabs_music_v1",
  "duration_seconds": 30,
  "include_details": false
}'

Response Example

{
  "id": "run_music_123",
  "object": "run",
  "status": "completed",
  "capability": "music_generation",
  "endpoint": "audio.music.create",
  "model": "music.elevenlabs_music_v1",
  "request_id": "run_img_123",
  "input_summary": {
    "prompt": "Studio product photo of a matte black water bottle",
    "model": "image.nano_banana_2",
    "aspect_ratio": "1:1",
    "count": 1
  },
  "output": {
    "audio_id": "audio_music_123",
    "audio_url": "https://cdn.genfire.ai/output/music-123.mp3",
    "duration": 30
  },
  "usage": {
    "credits": 8
  },
  "error": null,
  "resource_id": null,
  "provider_request_id": null,
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:02.000Z",
  "completed_at": "2026-03-25T12:00:02.000Z"
}

Request Example Body

{
  "prompt": "Confident electronic music bed for a product launch video",
  "model": "music.elevenlabs_music_v1",
  "duration_seconds": 30,
  "include_details": false
}

POST /audio/sfx

audio:write

Generate sound effects

Generate short sound effects or foley-style audio from a text prompt.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

prompt string required

The sound effect prompt.

model string optional

Optional sound effect model alias from `/models`.

Default: sfx.elevenlabs_v1

duration_seconds number optional

Optional desired duration in seconds.

output_format string optional

Optional output format when supported by the backing provider.

prompt_influence number optional

Optional prompt influence value when supported.

loop boolean optional

Whether to generate a loop-friendly result when supported.

curl Example

curl https://api.genfire.ai/v1/audio/sfx \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Heavy metal door slam in a large warehouse",
  "model": "sfx.elevenlabs_v1",
  "duration_seconds": 4
}'

Response Example

{
  "id": "run_sfx_123",
  "object": "run",
  "status": "completed",
  "capability": "sound_effect_generation",
  "endpoint": "audio.sfx.create",
  "model": "sfx.elevenlabs_v1",
  "request_id": "run_img_123",
  "input_summary": {
    "prompt": "Studio product photo of a matte black water bottle",
    "model": "image.nano_banana_2",
    "aspect_ratio": "1:1",
    "count": 1
  },
  "output": {
    "audio_id": "audio_sfx_123",
    "audio_url": "https://cdn.genfire.ai/output/sfx-123.mp3",
    "duration": 4.1
  },
  "usage": {
    "credits": 8
  },
  "error": null,
  "resource_id": null,
  "provider_request_id": null,
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:02.000Z",
  "completed_at": "2026-03-25T12:00:02.000Z"
}

Request Example Body

{
  "prompt": "Heavy metal door slam in a large warehouse",
  "model": "sfx.elevenlabs_v1",
  "duration_seconds": 4
}

POST /audio/transcriptions

audio:write

Transcribe audio or video (speech-to-text)

Transcribe speech to text with word- and segment-level timestamps using OpenAI Whisper. Provide exactly one of `audio_url`, `video_url`, or `youtube_url`. Video sources have their audio extracted automatically. Billed per second of media duration.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

audio_url string optional

URL of a direct audio file (mp3, wav, m4a, aac, ogg, flac, opus, webm, wma). One of audio_url / video_url / youtube_url is required.

video_url string optional

URL of a direct video file; audio is extracted before transcription.

youtube_url string optional

A YouTube URL to download and transcribe (max 2 hours).

model string optional

Optional transcription model alias from `/models`.

Default: transcription.whisper_v1

curl Example

curl https://api.genfire.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "audio_url": "https://cdn.genfire.ai/uploads/interview.mp3",
  "model": "transcription.whisper_v1"
}'

Response Example

{
  "id": "run_transcription_123",
  "object": "run",
  "status": "completed",
  "capability": "transcription",
  "endpoint": "audio.transcriptions.create",
  "model": "transcription.whisper_v1",
  "request_id": "run_img_123",
  "input_summary": {
    "prompt": "Studio product photo of a matte black water bottle",
    "model": "image.nano_banana_2",
    "aspect_ratio": "1:1",
    "count": 1
  },
  "output": {
    "transcript_id": "audio_txn_123",
    "text": "Welcome to the GenFire creative workflow.",
    "language": "en",
    "duration": 3.2,
    "words": [
      {
        "word": "Welcome",
        "start": 0,
        "end": 0.4,
        "probability": 1
      }
    ],
    "segments": [
      {
        "id": 0,
        "start": 0,
        "end": 3.2,
        "text": "Welcome to the GenFire creative workflow."
      }
    ],
    "audio_url": "https://storage.googleapis.com/genfire/extracted-audio/123.mp3"
  },
  "usage": {
    "credits": 8
  },
  "error": null,
  "resource_id": null,
  "provider_request_id": null,
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:02.000Z",
  "completed_at": "2026-03-25T12:00:02.000Z"
}

Request Example Body

{
  "audio_url": "https://cdn.genfire.ai/uploads/interview.mp3",
  "model": "transcription.whisper_v1"
}

Notes

Max media size 500MB; max duration 2 hours.
Async — usually returns a queued run first; poll the run until `status` is `completed`, then read `output.text` / `output.words` / `output.segments`.
YouTube transcription is supported but downloads third-party content — ensure your use complies with the source platform’s terms.

POST /products/extract

products:write

Extract product data from a URL

Scrape product details from a public product page and return the result inside a run envelope.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

url string required

A public product page URL. Private, local, and unsafe targets are blocked.

curl Example

curl https://api.genfire.ai/v1/products/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/products/matte-black-water-bottle"
}'

Response Example

{
  "id": "run_product_123",
  "object": "run",
  "status": "completed",
  "capability": "product_extraction",
  "endpoint": "products.extract.create",
  "model": null,
  "request_id": "run_img_123",
  "input_summary": {
    "prompt": "Studio product photo of a matte black water bottle",
    "model": "image.nano_banana_2",
    "aspect_ratio": "1:1",
    "count": 1
  },
  "output": {
    "product": {
      "success": true,
      "title": "Matte Black Water Bottle",
      "description": "Insulated stainless steel water bottle",
      "category": "hydration",
      "price": "$39",
      "images": [
        "https://example.com/product.jpg"
      ]
    },
    "cached": false
  },
  "usage": {
    "credits": 8
  },
  "error": null,
  "resource_id": null,
  "provider_request_id": null,
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:02.000Z",
  "completed_at": "2026-03-25T12:00:02.000Z"
}

Request Example Body

{
  "url": "https://example.com/products/matte-black-water-bottle"
}

Notes

Unsafe or private-network targets are rejected before scraping begins.

Reference

Workflows

GET /workflows

workflows:read

List executable workflows

Returns the workflow catalog. Use this when you want a higher-level outcome rather than raw media generation.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/workflows \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "hook_pack",
      "object": "workflow",
      "name": "Hook Pack",
      "description": "Generate three monetizable UGC-style hooks plus a supporting body and CTA.",
      "status": "available",
      "input_schema": {
        "type": "object",
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "type": "string"
          },
          "audience": {
            "type": "string"
          },
          "tone": {
            "type": "string",
            "enum": [
              "casual",
              "professional",
              "humorous",
              "educational",
              "persuasive",
              "emotional"
            ]
          },
          "length": {
            "type": "string",
            "enum": [
              "short",
              "medium",
              "long"
            ]
          },
          "target_duration": {
            "type": "number"
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "additional_requirements": {
            "type": "string"
          }
        }
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "hooks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "body": {
            "type": "string"
          },
          "call_to_action": {
            "type": "string"
          },
          "full_script": {
            "type": "string"
          }
        }
      }
    },
    {
      "id": "ugc_ad",
      "object": "workflow",
      "name": "UGC Ad Script",
      "description": "Generate an outcome-oriented UGC ad script with hooks, body, CTA, and a full spoken script.",
      "status": "available",
      "input_schema": {
        "type": "object",
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "type": "string"
          },
          "audience": {
            "type": "string"
          },
          "tone": {
            "type": "string",
            "enum": [
              "casual",
              "professional",
              "humorous",
              "educational",
              "persuasive",
              "emotional"
            ]
          },
          "length": {
            "type": "string",
            "enum": [
              "short",
              "medium",
              "long"
            ]
          },
          "target_duration": {
            "type": "number"
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "additional_requirements": {
            "type": "string"
          }
        }
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "hooks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "body": {
            "type": "string"
          },
          "call_to_action": {
            "type": "string"
          },
          "full_script": {
            "type": "string"
          }
        }
      }
    },
    {
      "id": "creative_pack",
      "object": "workflow",
      "name": "Creative Pack",
      "description": "Build a product-aware creative pack with analysis, angles, hooks, and a monetizable script.",
      "status": "available",
      "input_schema": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string"
          },
          "product_url": {
            "type": "string",
            "format": "uri"
          },
          "product_name": {
            "type": "string"
          },
          "product_description": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "audience": {
            "type": "string"
          },
          "tone": {
            "type": "string",
            "enum": [
              "casual",
              "professional",
              "humorous",
              "educational",
              "persuasive",
              "emotional"
            ]
          },
          "length": {
            "type": "string",
            "enum": [
              "short",
              "medium",
              "long"
            ]
          },
          "image_urls": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "additional_requirements": {
            "type": "string"
          }
        }
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "product": {
            "type": "object"
          },
          "analysis": {
            "type": "object"
          },
          "hooks": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "body": {
            "type": "string"
          },
          "call_to_action": {
            "type": "string"
          },
          "full_script": {
            "type": "string"
          }
        }
      }
    },
    {
      "id": "product_ad_variants",
      "object": "workflow",
      "name": "Product Ad Variants",
      "description": "Generate multiple UGC-style ad script variants for the same product or offer.",
      "status": "available",
      "input_schema": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string"
          },
          "product_name": {
            "type": "string"
          },
          "product_description": {
            "type": "string"
          },
          "audience": {
            "type": "string"
          },
          "tone": {
            "type": "string",
            "enum": [
              "casual",
              "professional",
              "humorous",
              "educational",
              "persuasive",
              "emotional"
            ]
          },
          "length": {
            "type": "string",
            "enum": [
              "short",
              "medium",
              "long"
            ]
          },
          "variant_count": {
            "type": "number",
            "minimum": 1,
            "maximum": 5
          },
          "additional_requirements": {
            "type": "string"
          }
        }
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "variant_count": {
            "type": "number"
          },
          "variants": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  ]
}

GET /workflows/{workflowKey}

workflows:read

Get one workflow definition

Returns the input and output schema for a specific workflow.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

workflowKey path required

A workflow id such as `hook_pack` or `creative_pack`.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/workflows/{workflowKey} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "id": "hook_pack",
  "object": "workflow",
  "name": "Hook Pack",
  "description": "Generate three monetizable UGC-style hooks plus a supporting body and CTA.",
  "status": "available",
  "input_schema": {
    "type": "object",
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string"
      },
      "audience": {
        "type": "string"
      },
      "tone": {
        "type": "string",
        "enum": [
          "casual",
          "professional",
          "humorous",
          "educational",
          "persuasive",
          "emotional"
        ]
      },
      "length": {
        "type": "string",
        "enum": [
          "short",
          "medium",
          "long"
        ]
      },
      "target_duration": {
        "type": "number"
      },
      "keywords": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "additional_requirements": {
        "type": "string"
      }
    }
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "hooks": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "body": {
        "type": "string"
      },
      "call_to_action": {
        "type": "string"
      },
      "full_script": {
        "type": "string"
      }
    }
  }
}

POST /workflows/{workflowKey}/runs

workflows:write

Execute a workflow

Creates a run for the requested workflow. The request body depends on the workflow you choose.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Parameters

workflowKey path required

A workflow id such as `hook_pack`, `ugc_ad`, or `creative_pack`.

Body Fields

workflow-specific fields object required

Use the schema from `GET /workflows/{workflowKey}` or the workflow catalog below.

curl Example

curl https://api.genfire.ai/v1/workflows/{workflowKey}/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Portable blender for busy professionals",
  "audience": "Remote workers who skip breakfast",
  "tone": "persuasive",
  "length": "short",
  "target_duration": 20,
  "keywords": [
    "protein shake",
    "commute",
    "healthy"
  ],
  "additional_requirements": "Lead with convenience and save time."
}'

Response Example

{
  "id": "run_workflow_123",
  "object": "run",
  "status": "completed",
  "capability": "workflow.hook_pack",
  "endpoint": "workflows.hook_pack.run",
  "model": null,
  "request_id": "run_img_123",
  "input_summary": {
    "workflow": "hook_pack",
    "prompt": "Portable blender for busy professionals",
    "audience": "Remote workers who skip breakfast",
    "tone": "persuasive",
    "length": "short",
    "target_duration": 20,
    "keywords": [
      "protein shake",
      "commute",
      "healthy"
    ],
    "additional_requirements": "Lead with convenience and save time."
  },
  "output": {
    "workflow": "hook_pack",
    "topic": "Portable blender for busy professionals",
    "hooks": [
      "If breakfast keeps losing to your calendar, this fixes it.",
      "I stopped skipping protein the day I threw this in my bag.",
      "This is how I make a full shake before my first meeting."
    ],
    "body": "Portable, fast, and easy to clean for daily use.",
    "call_to_action": "Try it before your next busy week.",
    "full_script": "If breakfast keeps losing to your calendar...",
    "word_count": 96,
    "estimated_duration": 22
  },
  "usage": {
    "credits": 8
  },
  "error": null,
  "resource_id": null,
  "provider_request_id": null,
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:02.000Z",
  "completed_at": "2026-03-25T12:00:02.000Z"
}

Request Example Body

{
  "prompt": "Portable blender for busy professionals",
  "audience": "Remote workers who skip breakfast",
  "tone": "persuasive",
  "length": "short",
  "target_duration": 20,
  "keywords": [
    "protein shake",
    "commute",
    "healthy"
  ],
  "additional_requirements": "Lead with convenience and save time."
}

Notes

The workflow catalog below includes example payloads for every supported workflow.

Reference

User Workflows

GET /user-workflows

workflows:read

List your editor workflows

Lists the node-graph workflows the authenticated account owns or can access through team sharing — the same workflows shown in the dashboard workflow editor. Use the returned `id` to trigger runs via `POST /user-workflows/{workflowId}/runs`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/user-workflows \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "wf_abc123",
      "object": "user_workflow",
      "title": "Product shot pipeline",
      "nodeCount": 6,
      "updatedAt": "2026-07-01T12:00:00.000Z",
      "teamId": null
    }
  ]
}

POST /user-workflows/{workflowId}/runs

workflows:write

Run one of your editor workflows

Starts a run of a user-created workflow graph — the same execution path as the editor’s Run button. Execution is asynchronous: this returns `202 Accepted` immediately with a run id; poll `GET /user-workflows/{workflowId}/runs/{runId}` for progress and per-node outputs. Credits are charged to the authenticated account per node as the graph executes (runner pays).

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

workflowId path required

A workflow id from `GET /user-workflows`.

Body Fields

pageId string optional

Which page of the workflow to run. Defaults to the first page.

selectedNodeIds array optional

Node ids to run — their upstream dependencies run automatically. Defaults to the editor behavior: the page’s Export nodes if it has any, otherwise every generation leaf node (image/video/audio/text nodes with no outgoing edges).

paramOverrides object optional

Per-run parameter overrides shaped as `{ nodeId: { paramKey: value } }`. Values must be primitives (string, number, boolean, or null) and the object must serialize to at most 50KB. Overrides apply to this run only — the stored workflow is never modified.

curl Example

curl https://api.genfire.ai/v1/user-workflows/{workflowId}/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "pageId": "page_1",
  "paramOverrides": {
    "node_prompt_1": {
      "text": "A red sneaker on a marble table"
    }
  }
}'

Response Example

{
  "runId": "wfrun_abc123",
  "totalCostCredits": 42,
  "pageId": "page_1",
  "selectedNodeIds": [
    "node_export_1"
  ]
}

Request Example Body

{
  "pageId": "page_1",
  "paramOverrides": {
    "node_prompt_1": {
      "text": "A red sneaker on a marble table"
    }
  }
}

Notes

Requires owner or editor access to the workflow; team viewers receive a 403.
`totalCostCredits` is the up-front estimate for the nodes that will execute; per-node charges settle against your credit balance as the run progresses.
Snake_case body keys (`page_id`, `selected_node_ids`, `param_overrides`) are accepted as aliases.

GET /user-workflows/{workflowId}/runs/{runId}

workflows:read

Get the status and outputs of a workflow run

Returns run-level status plus one entry per executed node with its output media URL or text. Poll until `status` is `completed`, `failed`, or `cancelled`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

workflowId path required

A workflow id from `GET /user-workflows`.

runId path required

The run id returned by `POST /user-workflows/{workflowId}/runs`.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/user-workflows/{workflowId}/runs/{runId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "runId": "wfrun_abc123",
  "workflowId": "wf_abc123",
  "pageId": "page_1",
  "status": "completed",
  "totalCostCredits": 42,
  "startedAt": "2026-07-01T12:00:01.000Z",
  "completedAt": "2026-07-01T12:02:40.000Z",
  "error": null,
  "nodes": [
    {
      "nodeId": "node_image_1",
      "status": "completed",
      "output": {
        "type": "image",
        "url": "https://firebasestorage.googleapis.com/.../shot.png"
      }
    },
    {
      "nodeId": "node_export_1",
      "status": "completed",
      "output": {
        "type": "file",
        "url": "https://firebasestorage.googleapis.com/.../export.png"
      }
    }
  ]
}

Reference

Batches

GET /batches

batches:read

List recent batches

Lists batch jobs created by the authenticated account.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

status query optional

Optional status filter such as `queued`, `processing`, `completed`, `failed`, or `partial`.

mode query optional

Optional batch mode filter: `workflow` or `operation`.

target query optional

Optional target filter such as `hook_pack` or `images.generations.create`.

limit query optional

Maximum number of batches to return.

Default: 25

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/batches \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "batch_123",
      "object": "batch",
      "mode": "workflow",
      "target": "hook_pack",
      "status": "queued",
      "total_items": 2,
      "completed_items": 0,
      "failed_items": 0,
      "concurrency": 2,
      "input_summary": {
        "mode": "workflow",
        "target": "hook_pack",
        "item_count": 2
      },
      "output": null,
      "error": null,
      "created_at": "2026-03-25T12:00:00.000Z",
      "updated_at": "2026-03-25T12:00:00.000Z",
      "completed_at": null
    }
  ]
}

GET /batches/{batchId}

batches:read

Get a batch by id

Returns batch-level status, counts, and summary output.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

batchId path required

The batch id returned by `POST /batches`.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/batches/{batchId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "id": "batch_123",
  "object": "batch",
  "mode": "workflow",
  "target": "hook_pack",
  "status": "queued",
  "total_items": 2,
  "completed_items": 0,
  "failed_items": 0,
  "concurrency": 2,
  "input_summary": {
    "mode": "workflow",
    "target": "hook_pack",
    "item_count": 2
  },
  "output": null,
  "error": null,
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:00.000Z",
  "completed_at": null
}

GET /batches/{batchId}/items

batches:read

List items in a batch

Returns one row per batch item so you can inspect per-item progress and run ids.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

batchId path required

The batch id returned by `POST /batches`.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/batches/{batchId}/items \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "batch_item_123",
      "object": "batch_item",
      "batch_id": "batch_123",
      "index": 0,
      "target": "hook_pack",
      "status": "queued",
      "run_id": null,
      "input_summary": {
        "prompt": "Portable blender for busy professionals"
      },
      "output": null,
      "error": null,
      "created_at": "2026-03-25T12:00:00.000Z",
      "updated_at": "2026-03-25T12:00:00.000Z",
      "completed_at": null
    }
  ]
}

POST /batches

batches:write

Create a batch

Create a batch over workflows or selected generation operations. Each item becomes its own run when processed.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

mode string required

Use `workflow` for workflow batches or `operation` for supported primitive operations.

target string required

Workflow key or supported operation target such as `images.generations.create`.

concurrency number optional

How many items to process concurrently.

Default: 2

items array required

Array of batch items. Each item must have an `input` object.

curl Example

curl https://api.genfire.ai/v1/batches \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "workflow",
  "target": "hook_pack",
  "concurrency": 2,
  "items": [
    {
      "input": {
        "prompt": "Portable blender for busy professionals"
      }
    },
    {
      "input": {
        "prompt": "Portable blender for college students"
      }
    }
  ]
}'

Response Example

{
  "id": "batch_123",
  "object": "batch",
  "mode": "workflow",
  "target": "hook_pack",
  "status": "queued",
  "total_items": 2,
  "completed_items": 0,
  "failed_items": 0,
  "concurrency": 2,
  "input_summary": {
    "mode": "workflow",
    "target": "hook_pack",
    "item_count": 2
  },
  "output": null,
  "error": null,
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:00.000Z",
  "completed_at": null,
  "items": [
    {
      "id": "batch_item_123",
      "object": "batch_item",
      "batch_id": "batch_123",
      "index": 0,
      "target": "hook_pack",
      "status": "queued",
      "run_id": null,
      "input_summary": {
        "prompt": "Portable blender for busy professionals"
      },
      "output": null,
      "error": null,
      "created_at": "2026-03-25T12:00:00.000Z",
      "updated_at": "2026-03-25T12:00:00.000Z",
      "completed_at": null
    },
    {
      "id": "batch_item_124",
      "object": "batch_item",
      "batch_id": "batch_123",
      "index": 1,
      "target": "hook_pack",
      "status": "queued",
      "run_id": null,
      "input_summary": {
        "prompt": "Portable blender for college students"
      },
      "output": null,
      "error": null,
      "created_at": "2026-03-25T12:00:00.000Z",
      "updated_at": "2026-03-25T12:00:00.000Z",
      "completed_at": null
    }
  ]
}

Request Example Body

{
  "mode": "workflow",
  "target": "hook_pack",
  "concurrency": 2,
  "items": [
    {
      "input": {
        "prompt": "Portable blender for busy professionals"
      }
    },
    {
      "input": {
        "prompt": "Portable blender for college students"
      }
    }
  ]
}

Notes

Current operation batches support `images.generations.create` and `videos.generations.create`.
Workflow batches support any workflow listed by `GET /workflows`.
Items in `operation`-mode batches accept the same body fields as the operation `target` — e.g. `quality` and `resolution` are honored when batching `images.generations.create`.

Reference

Webhooks

GET /webhooks

webhooks:read

List webhook endpoints

Returns webhook destinations registered for the authenticated account.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "wh_123",
      "object": "webhook_endpoint",
      "url": "https://example.com/webhooks/genfire",
      "description": "Agency production endpoint",
      "status": "active",
      "events": [
        "run.completed",
        "run.failed"
      ],
      "signing_secret_preview": "gfwsec_1234...abcd",
      "created_at": "2026-03-25T12:00:00.000Z",
      "updated_at": "2026-03-25T12:00:00.000Z",
      "last_delivery_at": null
    }
  ]
}

GET /webhooks/deliveries

webhooks:read

List webhook deliveries

Returns delivery attempts for the authenticated account.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

endpoint_id query optional

Optional webhook endpoint id to filter deliveries.

limit query optional

Maximum number of deliveries to return.

Default: 25

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/webhooks/deliveries \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "delivery_123",
      "object": "webhook_delivery",
      "endpoint_id": "wh_123",
      "event_type": "run.completed",
      "run_id": "run_img_123",
      "batch_id": null,
      "status": "success",
      "attempt_count": 1,
      "max_attempts": 6,
      "response_status": 200,
      "response_body": "ok",
      "last_error": null,
      "request_headers": {
        "X-GenFire-Signature": "sha256=..."
      },
      "created_at": "2026-03-25T12:00:05.000Z",
      "updated_at": "2026-03-25T12:00:05.000Z",
      "last_attempt_at": "2026-03-25T12:00:05.000Z",
      "next_attempt_at": null,
      "delivered_at": "2026-03-25T12:00:05.000Z"
    }
  ]
}

POST /webhooks

webhooks:write

Create a webhook endpoint

Registers a webhook destination and returns the signing secret once.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

url string required

Public HTTPS endpoint that will receive webhook POST requests.

description string optional

Optional human-readable label for the endpoint.

events array optional

Optional list of event types to subscribe to.

Default: ["run.completed","run.failed"]

curl Example

curl https://api.genfire.ai/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/genfire",
  "description": "Agency production endpoint",
  "events": [
    "run.completed",
    "run.failed"
  ]
}'

Response Example

{
  "id": "wh_123",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/genfire",
  "description": "Agency production endpoint",
  "status": "active",
  "events": [
    "run.completed",
    "run.failed"
  ],
  "signing_secret_preview": "gfwsec_1234...abcd",
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:00:00.000Z",
  "last_delivery_at": null,
  "signing_secret": "gfwsec_live_example_secret"
}

Request Example Body

{
  "url": "https://example.com/webhooks/genfire",
  "description": "Agency production endpoint",
  "events": [
    "run.completed",
    "run.failed"
  ]
}

Notes

Store the signing secret immediately. It is only returned when the endpoint is created.

POST /webhooks/deliveries/{deliveryId}/replay

webhooks:write

Replay a webhook delivery

Queues a new delivery attempt for an existing webhook delivery record.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

deliveryId path required

The webhook delivery id.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/webhooks/deliveries/{deliveryId}/replay \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "id": "delivery_456",
  "object": "webhook_delivery",
  "endpoint_id": "wh_123",
  "event_type": "run.completed",
  "run_id": "run_img_123",
  "batch_id": null,
  "status": "pending",
  "attempt_count": 0,
  "max_attempts": 6,
  "response_status": null,
  "response_body": null,
  "last_error": null,
  "request_headers": {
    "X-GenFire-Signature": "sha256=..."
  },
  "created_at": "2026-03-25T12:00:05.000Z",
  "updated_at": "2026-03-25T12:00:05.000Z",
  "last_attempt_at": null,
  "next_attempt_at": null,
  "delivered_at": null
}

PATCH /webhooks/{endpointId}

webhooks:write

Update a webhook endpoint

Update a webhook URL, description, status, or subscribed events.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

endpointId path required

The webhook endpoint id.

Body Fields

url string optional

New destination URL.

description string | null optional

New description or `null` to clear it.

status string optional

Use `active` or `disabled`.

events array optional

Replacement list of subscribed event types.

curl Example

curl https://api.genfire.ai/v1/webhooks/{endpointId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "disabled"
}'

Response Example

{
  "id": "wh_123",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/genfire",
  "description": "Agency production endpoint",
  "status": "disabled",
  "events": [
    "run.completed",
    "run.failed"
  ],
  "signing_secret_preview": "gfwsec_1234...abcd",
  "created_at": "2026-03-25T12:00:00.000Z",
  "updated_at": "2026-03-25T12:05:00.000Z",
  "last_delivery_at": null
}

Request Example Body

{
  "status": "disabled"
}

DELETE /webhooks/{endpointId}

webhooks:write

Delete a webhook endpoint

Deletes the webhook endpoint. The endpoint id is no longer usable after deletion.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

endpointId path required

The webhook endpoint id.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/webhooks/{endpointId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

204 No Content

Reference

Faceless Reels

POST /faceless-reels/generations

reels:write

Generate a faceless reel

Generates a vertical (9:16) short end-to-end: LLM script → voiceover → style-locked images → music → captioned video. Async — returns a run in `processing`; poll `GET /v1/runs/{runId}` until it is `completed`, then read the `video_url` from `output`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

topic string required

The subject / seed for the reel. Use a phrase like "the disappearance of the Sodder children" or "Surprise me with a fresh idea".

preset_id string optional

Niche preset id from `GET /v1/faceless-reels/presets` (drives topic + tone). Defaults to a creepy-story preset.

style_id string optional

Visual style id from `GET /v1/faceless-reels/styles`. Defaults to the preset’s recommended style.

target_duration_sec number optional

Target length in seconds (10–600, up to 10 minutes). Drives script + scene count. Defaults to the niche’s natural length.

caption_preset_id string optional

Caption font/animation preset from `GET /v1/faceless-reels/caption-presets`.

Default: hormozi

caption_animation string optional

Override the caption animation (highlight | pop | typewriter | classic | background).

caption_position string optional

Vertical caption placement: "top" | "middle" | "bottom". Default middle (the classic centered render).

Default: middle

voice_id string optional

TTS voice id (ElevenLabs or FAL/Qwen). Defaults to a built-in narrator voice.

motion_vibe string optional

Camera-motion feel for the image slideshow: "auto" (per-niche, default) | "calm" (slow pans, subtle zoom) | "dynamic" (mixed pans + zooms) | "energetic" (corner punch-ins + shake).

Default: auto

animation_mode string optional

How much of the reel is real video: "stills" (Ken-Burns slideshow, default) | "hook" (premium — the FIRST scene is a real omni image-to-video clip) | "full" (ultra — EVERY scene is a real omni clip, one i2v clip cost per scene). Wins over animated_hook.

Default: stills

animated_hook boolean optional

LEGACY: true ≈ animation_mode "hook". Prefer animation_mode.

Default: false

video_model string optional

i2v model for animated clips. Every value resolves to "omni" (gemini-omni-flash); "grok"/"seedance-mini" are accepted legacy aliases.

Default: omni

direction string optional

Extra creative direction passed to the script model.

custom_story object optional

{ prompt, scene_hint? } to author a fully custom story instead of using a niche preset.

music object optional

Background music: { source: "none"|"preset"|"ai"|"library", preset_id?, prompt?, track_id? }.

curl Example

curl https://api.genfire.ai/v1/faceless-reels/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "The unsolved mystery of the Mary Celeste",
  "preset_id": "mystery",
  "target_duration_sec": 45,
  "caption_preset_id": "hormozi",
  "music": {
    "source": "preset",
    "preset_id": "unsolved-mystery"
  }
}'

Response Example

{
  "id": "run_8f3c4a2b1d6e7f9a0b1c2d3e",
  "object": "run",
  "status": "processing",
  "capability": "faceless_reel_generation",
  "endpoint": "faceless_reels.generations.create",
  "model": "reel.faceless",
  "resource_id": "reel_abc123",
  "created_at": "2026-06-08T12:00:00.000Z"
}

Request Example Body

{
  "topic": "The unsolved mystery of the Mary Celeste",
  "preset_id": "mystery",
  "target_duration_sec": 45,
  "caption_preset_id": "hormozi",
  "music": {
    "source": "preset",
    "preset_id": "unsolved-mystery"
  }
}

Notes

A reel renders in minutes. Poll `GET /v1/runs/{runId}` until `completed`; the output carries `{ reel_id, video_url, script, scenes, duration_seconds }`.
Cost varies with duration and music. Call `POST /v1/faceless-reels/estimate-cost` first for a per-config credit estimate.
The same `Idempotency-Key` returns the same run instead of generating (and billing) twice.

POST /faceless-reels/estimate-cost

reels:read

Estimate reel credit cost

Returns a per-config credit breakdown (images + voiceover + music) for a prospective reel, without generating anything.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

preset_id string optional

Niche preset id (affects default scene count).

target_duration_sec number optional

Target length in seconds (10–600, up to 10 minutes).

music object optional

Music config; only `source: "ai"` adds a music fee.

curl Example

curl https://api.genfire.ai/v1/faceless-reels/estimate-cost \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "preset_id": "mystery",
  "target_duration_sec": 45,
  "music": {
    "source": "preset"
  }
}'

Response Example

{
  "object": "reel_cost_estimate",
  "images": 18,
  "voiceover": 6,
  "music": 0,
  "total": 24,
  "sceneCount": 7
}

Request Example Body

{
  "preset_id": "mystery",
  "target_duration_sec": 45,
  "music": {
    "source": "preset"
  }
}

GET /faceless-reels/presets

reels:read

List niche presets

Lists the available niche presets (topic + tone) that can be passed as `preset_id`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/faceless-reels/presets \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "mystery",
      "label": "Unsolved Mystery",
      "emoji": "🔍",
      "tone": "mystery",
      "recommendedStyleId": "cinematic"
    }
  ]
}

GET /faceless-reels/styles

reels:read

List visual styles

Lists the available visual styles (art mediums) that can be passed as `style_id`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/faceless-reels/styles \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "cinematic",
      "label": "Cinematic",
      "emoji": "🎬",
      "group": "Realistic"
    }
  ]
}

GET /faceless-reels/music-presets

reels:read

List background-music presets

Lists curated background-music tracks usable with `music.source = "preset"`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/faceless-reels/music-presets \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "unsolved-mystery",
      "label": "Unsolved Mystery",
      "mood": "mystery"
    }
  ]
}

GET /faceless-reels/caption-presets

reels:read

List caption presets

Lists caption font/animation presets usable as `caption_preset_id`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/faceless-reels/caption-presets \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "hormozi",
      "label": "Hormozi",
      "animation": "highlight"
    }
  ]
}

GET /faceless-reels/subscriptions

reels:read

List reel subscriptions

Lists the account owner’s recurring reel subscriptions ("Stories"). Each defines a niche + schedule that auto-generates reels.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/faceless-reels/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "sub_abc123",
      "enabled": true,
      "presetId": "mystery",
      "cadencePerDay": 1,
      "slots": [
        "18:00"
      ],
      "timezone": "America/New_York"
    }
  ]
}

POST /faceless-reels/subscriptions

reels:write

Create a reel subscription

Creates a recurring "Story" that auto-generates reels on a daily schedule. Accepts the same creative fields as one-off generation plus scheduling and topic-rotation fields.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

label string optional

A name for the Story.

preset_id string optional

Niche preset id.

style_id string optional

Visual style id.

caption_preset_id string optional

Caption preset id.

caption_position string optional

Vertical caption placement: "top" | "middle" | "bottom".

Default: middle

voice_id string optional

TTS voice id.

motion_vibe string optional

Camera-motion feel: "auto" | "calm" | "dynamic" | "energetic".

Default: auto

animation_mode string optional

Animation tier: "stills" | "hook" (first scene animated) | "full" (every scene a real omni clip).

Default: stills

animated_hook boolean optional

LEGACY: true ≈ animation_mode "hook".

Default: false

video_model string optional

i2v model for animated clips (every value resolves to "omni").

Default: omni

target_duration_sec number optional

Target length (10–600, up to 10 minutes).

music object optional

Background music config.

topic_source string optional

"ai-auto" (fresh ideas) or "user-list" (rotate `topic_seeds`).

Default: ai-auto

topic_seeds array optional

Topics to rotate through when `topic_source` is "user-list".

cadence_per_day number optional

Reels per day (1–6).

Default: 1

slots array optional

Local "HH:mm" times; length must equal `cadence_per_day`.

Default: ["18:00"]

timezone string optional

IANA timezone for the slots.

Default: America/New_York

enabled boolean optional

Whether the schedule is active.

Default: true

curl Example

curl https://api.genfire.ai/v1/faceless-reels/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Daily mysteries",
  "preset_id": "mystery",
  "cadence_per_day": 1,
  "slots": [
    "18:00"
  ],
  "timezone": "America/New_York",
  "topic_source": "ai-auto"
}'

Response Example

{
  "object": "reel_subscription",
  "id": "sub_abc123",
  "enabled": true,
  "presetId": "mystery",
  "cadencePerDay": 1,
  "slots": [
    "18:00"
  ],
  "timezone": "America/New_York"
}

Request Example Body

{
  "label": "Daily mysteries",
  "preset_id": "mystery",
  "cadence_per_day": 1,
  "slots": [
    "18:00"
  ],
  "timezone": "America/New_York",
  "topic_source": "ai-auto"
}

PATCH /faceless-reels/subscriptions/{id}

reels:write

Update a reel subscription

Updates fields on a reel subscription. Changing cadence/slots/timezone recomputes the schedule.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

id path required

Subscription id.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/faceless-reels/subscriptions/{id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": false
}'

Response Example

{
  "object": "reel_subscription",
  "id": "sub_abc123",
  "enabled": false
}

Request Example Body

{
  "enabled": false
}

DELETE /faceless-reels/subscriptions/{id}

reels:write

Delete a reel subscription

Deletes a reel subscription. Already-generated reels are unaffected.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Parameters

id path required

Subscription id.

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/faceless-reels/subscriptions/{id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "reel_subscription",
  "id": "sub_abc123",
  "deleted": true
}

POST /faceless-reels/subscriptions/{id}/run-now

reels:write

Generate a reel now for a subscription

Manually triggers one reel for a subscription right now (async run), using the subscription’s settings. Returns 409 if a reel is already generating for that subscription.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Parameters

id path required

Subscription id.

Body Fields

topic string optional

Optional topic override for this run; otherwise resolved from the subscription.

curl Example

curl https://api.genfire.ai/v1/faceless-reels/subscriptions/{id}/run-now \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "The vanishing of Flight 19"
}'

Response Example

{
  "id": "run_8f3c4a2b1d6e7f9a0b1c2d3e",
  "object": "run",
  "status": "processing",
  "capability": "faceless_reel_generation",
  "endpoint": "faceless_reels.subscriptions.run_now",
  "model": "reel.faceless",
  "resource_id": "reel_abc123",
  "created_at": "2026-06-08T12:00:00.000Z"
}

Request Example Body

{
  "topic": "The vanishing of Flight 19"
}

Notes

Poll `GET /v1/runs/{runId}` for the finished video, same as one-off generation.

Reference

Explainers

POST /explainers/generations

reels:write

Generate an explainer video

Generates a long-form narrated explainer/documentary (20s–10min, 16:9 or 9:16): script → expressive voiceover → style-locked frames → Gemini Omni Flash video clips per scene → composed film with optional captions. Pass a structured `script` to author the ENTIRE creative contract with your own model (agents: write the beats yourself — narration, shot-specs, motion notes, render modes, reference routing, emphasis words, recurring cast) and GenFire only renders; or pass just `topic` and GenFire writes the script. Async — returns a run in `processing`; poll `GET /v1/runs/{runId}`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Required

Body Fields

topic string required

What the explainer is about. Also used as the video title. Required even with a `script` (labels the run + video).

script object optional

Structured agent-authored script: { cast?: [{ name, description }] (≤3, UPPERCASE names, one fixed visual identity each), beats: [{ narration (spoken words, may carry ElevenLabs v3 [audio tags]), visual (concrete storyboard shot-spec with quoted on-screen labels), motion? (camera/animation director note), render? ("anchored"|"direct"), continues? (bool — continue previous shot via last-frame chaining; prefer true on most beats so the film flows as continuous footage, breaking only at deliberate scene changes; never where a cast member enters/returns — their introduction needs an anchored shot), refs? ([1-based reference_images indices]), emphasis? (≤3 verbatim narration substrings for keyword captions), cast? ([declared names]) }] (3–100 beats). Bypasses EVERY internal LLM call; narration length sets the duration (target_duration_sec is ignored). Validation errors return 400 `invalid_script` with the exact fix.

custom_script string optional

Plain word-for-word narration (no beat structure). GenFire still storyboards the visuals for you. Ignored when `script` is present.

style_id string optional

Visual style preset from `GET /v1/explainers/styles` (41 looks: pixel-art, claymation, whiteboard-doodle…). Defaults to a 2D-illustration look.

aspect_ratio string optional

"16:9" (default) or "9:16".

Default: 16:9

target_duration_sec number optional

Target runtime in seconds (20–600). Ignored when `script` is present — the narration length sets the duration.

Default: 60

voice_id string optional

Narration voice id (ElevenLabs; renders on eleven_v3 with expressive [audio tags]). Defaults to a documentary narrator.

motion_level string optional

How many scenes render as real omni video clips: "full" (every scene, default) | "mixed" (every 5th) | "stills" (Ken-Burns only, cheapest). Draft-run lever for agents.

Default: full

music object optional

Background music bed: { source: "none"|"preset"|"ai"|"library", preset_id?, prompt?, track_id? }.

caption_preset_id string optional

Captions are OPT-IN — omit for none. Any caption preset id from `GET /v1/faceless-reels/caption-presets` enables burned captions.

Default: none

caption_position string optional

Vertical caption placement: "top" | "middle" | "bottom" (default when captions are on).

caption_mode string optional

"full" burns the transcript; "keywords" pops only each beat's emphasis words at their spoken timestamps.

Default: full

caption_animation string optional

Override the caption animation (highlight | pop | typewriter | classic | background).

reference_images array optional

Up to 8 { url (https), label? (≤60 chars) } — products/characters/brands that must appear. Beats reference them via `refs` (1-based); those scenes render via omni reference-to-video. Put `refs: [1]` on the FIRST beat — the opening frame is generated as an image EDIT from the refs, locking the subject's real identity into the style anchor every later scene inherits.

curl Example

curl https://api.genfire.ai/v1/explainers/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique_request_key" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "How quantum computers actually work",
  "script": {
    "cast": [
      {
        "name": "QUBIT",
        "description": "a glowing translucent blue sphere with orbiting light rings, softly pulsing"
      }
    ],
    "beats": [
      {
        "narration": "Your laptop thinks in bits — tiny switches that are either on, or off.",
        "visual": "Clean diagram: a row of light switches on a circuit board, each labeled \"0\" or \"1\", one flipping",
        "motion": "Slow push-in as one switch flips",
        "emphasis": [
          "bits"
        ]
      },
      {
        "narration": "[curious] A quantum computer thinks in qubits — and a qubit can be both at once.",
        "visual": "QUBIT hovering between two glowing labels \"0\" and \"1\", overlapping into a blended glow labeled \"BOTH\"",
        "motion": "QUBIT drifts between the labels, rings spinning up",
        "cast": [
          "QUBIT"
        ],
        "emphasis": [
          "qubits",
          "both at once"
        ]
      },
      {
        "narration": "That superposition lets it explore millions of answers at the same time.",
        "visual": "Wide shot: QUBIT at the center of a branching tree of thousands of faint answer-paths lighting up simultaneously, label \"1,000,000 paths\"",
        "motion": "Camera pulls back as the tree ignites outward",
        "cast": [
          "QUBIT"
        ],
        "emphasis": [
          "superposition"
        ]
      }
    ]
  },
  "aspect_ratio": "16:9",
  "style_id": "2d-illustrator",
  "caption_preset_id": "minimal",
  "caption_mode": "keywords"
}'

Response Example

{
  "id": "run_8f3c4a2b1d6e7f9a0b1c2d3e",
  "object": "run",
  "status": "processing",
  "capability": "explainer_generation",
  "endpoint": "explainers.generations.create",
  "model": "explainer.omni",
  "resource_id": "reel_abc123",
  "created_at": "2026-07-06T12:00:00.000Z"
}

Request Example Body

{
  "topic": "How quantum computers actually work",
  "script": {
    "cast": [
      {
        "name": "QUBIT",
        "description": "a glowing translucent blue sphere with orbiting light rings, softly pulsing"
      }
    ],
    "beats": [
      {
        "narration": "Your laptop thinks in bits — tiny switches that are either on, or off.",
        "visual": "Clean diagram: a row of light switches on a circuit board, each labeled \"0\" or \"1\", one flipping",
        "motion": "Slow push-in as one switch flips",
        "emphasis": [
          "bits"
        ]
      },
      {
        "narration": "[curious] A quantum computer thinks in qubits — and a qubit can be both at once.",
        "visual": "QUBIT hovering between two glowing labels \"0\" and \"1\", overlapping into a blended glow labeled \"BOTH\"",
        "motion": "QUBIT drifts between the labels, rings spinning up",
        "cast": [
          "QUBIT"
        ],
        "emphasis": [
          "qubits",
          "both at once"
        ]
      },
      {
        "narration": "That superposition lets it explore millions of answers at the same time.",
        "visual": "Wide shot: QUBIT at the center of a branching tree of thousands of faint answer-paths lighting up simultaneously, label \"1,000,000 paths\"",
        "motion": "Camera pulls back as the tree ignites outward",
        "cast": [
          "QUBIT"
        ],
        "emphasis": [
          "superposition"
        ]
      }
    ]
  },
  "aspect_ratio": "16:9",
  "style_id": "2d-illustrator",
  "caption_preset_id": "minimal",
  "caption_mode": "keywords"
}

Notes

Explainers render in minutes to tens of minutes (a 10-minute film ≈ 30 min). Poll `GET /v1/runs/{runId}` — in-flight runs carry a `progress` stage card; completed output is `{ reel_id, video_url, script, scenes: [{ index, video_url, poster_url, prompt, narration, duration_sec, animated }], duration_seconds }` (per-scene clips included).
Cost scales with duration — call `POST /v1/explainers/estimate-cost` first (same body; with a `script` the quote derives from the narration length).
Structured-script authoring rules: `emphasis` phrases must quote the beat's spoken narration VERBATIM; `refs` must point at supplied reference_images; `cast` names must be declared in script.cast; a beat's visual is a concrete storyboard shot (subjects + composition + quoted on-screen text), never a metaphor.
The same `Idempotency-Key` returns the same run instead of generating (and billing) twice.

POST /explainers/estimate-cost

reels:read

Estimate explainer credit cost

Returns a per-config credit breakdown (frames + voiceover + music + video clips) for a prospective explainer, without generating anything. Accepts the same body as generate; with a `script` the duration derives from the narration length.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

target_duration_sec number optional

Target runtime in seconds (20–600). Ignored when `script` is present.

script object optional

Structured script (same shape as generate) — the quote derives from its narration length.

motion_level string optional

"full" | "mixed" | "stills" — how many scenes render as real video clips (the dominant cost lever).

Default: full

music object optional

Music config; only `source: "ai"` adds a music fee.

voice_id string optional

Narration voice (a Seed Audio preset switches the TTS credit key).

aspect_ratio string optional

"16:9" | "9:16" (no cost impact today; accepted for parity).

curl Example

curl https://api.genfire.ai/v1/explainers/estimate-cost \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target_duration_sec": 120,
  "motion_level": "full",
  "music": {
    "source": "preset"
  }
}'

Response Example

{
  "object": "explainer_cost_estimate",
  "effective_duration_sec": 120,
  "images": 42,
  "voiceover": 18,
  "music": 0,
  "videoClips": 220,
  "total": 280,
  "sceneCount": 20,
  "animatedScenes": 20
}

Request Example Body

{
  "target_duration_sec": 120,
  "motion_level": "full",
  "music": {
    "source": "preset"
  }
}

GET /explainers/styles

reels:read

List explainer visual styles

Lists the explainer visual style presets that can be passed as `style_id`.

Auth: Bearer API key or OAuth access token

Idempotency-Key: Not required

Body Fields

No body fields for this endpoint.

curl Example

curl https://api.genfire.ai/v1/explainers/styles \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "object": "list",
  "data": [
    {
      "id": "pixel-art",
      "label": "Pixel Art"
    },
    {
      "id": "claymation",
      "label": "Claymation"
    }
  ]
}