Skip to main content
POST
Starts async video generation and returns a canonical video_id. Poll GET /api/partner/v1/studio/videos/{videoId} for final state.

​
Idempotency

Send a unique Idempotency-Key header for each video you intend to generate. Retrying the same key with the same body replays the original operation. When the header is omitted, Genviral derives a stable key from the credential and request body for backward compatibility, so an identical headerless request is treated as a retry rather than a new generation.

​
Body Parameters

​
string
required
Video model ID from Get Studio Models.
​
string
Optional generation prompt. For prompt-driven models such as openai/sora-2 and google/veo-3, include any desired spoken dialogue directly in this field.
​
string
Optional speech text for explicit talking-head/lipsync models only (currently veed/fabric-1.0 and creatify/lipsync). Prompt-driven models such as openai/sora-2 and google/veo-3 do not accept speech_text; use prompt instead.
​
string
Optional voice identifier used with speech_text for explicit talking-head/lipsync flows. Prompt-driven models such as openai/sora-2 and google/veo-3 do not accept voice_id. For supported speech-input models, use Genviral voice IDs (for example george, sarah, aria); if omitted or unrecognized, Genviral falls back to a default voice.
​
string
Optional input image URL for image-to-video models.
​
string
Optional input video URL for video-to-video models.
​
string
Optional external audio URL for models that explicitly accept audio input (currently talking-head/lipsync flows and bytedance/seedance-2.0 reference-to-video). For Seedance, provide at least one image or video reference when sending audio.
​
string[]
Optional Seedance 2.0 reference images. Up to 9 images. Refer to them in the prompt as @Image1, @Image2, etc.
​
string[]
Optional Seedance 2.0 reference videos. Up to 3 videos. Refer to them in the prompt as @Video1, @Video2, etc.
​
string[]
Optional Seedance 2.0 reference audio clips. Up to 3 clips. Refer to them in the prompt as @Audio1, @Audio2, etc. Requires at least one image or video reference.
​
string
Optional negative prompt.
​
object
Normalized video params. Supported keys: resolution, duration_seconds, fps, aspect_ratio, generate_audio.
​
object
Optional model-specific passthrough params.

​
Example

​
Error Responses

  • 400 invalid_json - request body is not valid JSON
  • 401 - authentication failed (missing/invalid/revoked token)
  • 402 subscription_required - active Creator/Professional/Business plan required
  • 403 tier_not_allowed - Scheduler tier cannot use Partner API
  • 403 insufficient_credits
  • 422 invalid_payload (includes unsupported model_id)
  • 422 invalid_input
  • 500 generation_failed