{
"model_id": "bytedance/seedance-2.0",
"prompt": "Cinematic product reveal using @Image1 as the product style reference",
"reference_image_urls": ["https://example.com/product.jpg"],
"params": {
"duration_seconds": 5,
"aspect_ratio": "9:16",
"generate_audio": true
}
}
{
"ok": true,
"code": 202,
"message": "Video generation started",
"data": {
"video_id": "22222222-2222-2222-2222-222222222222",
"prediction_id": "pred_abc123",
"provider": "fal",
"model_id": "openai/sora-2",
"status": "processing",
"output_url": null,
"credits_used": 5
}
}
Studio AI
Generate Studio Video
Start async AI Studio video generation and return canonical video_id for polling.
POST
/
api
/
partner
/
v1
/
studio
/
videos
/
generate
{
"model_id": "bytedance/seedance-2.0",
"prompt": "Cinematic product reveal using @Image1 as the product style reference",
"reference_image_urls": ["https://example.com/product.jpg"],
"params": {
"duration_seconds": 5,
"aspect_ratio": "9:16",
"generate_audio": true
}
}
{
"ok": true,
"code": 202,
"message": "Video generation started",
"data": {
"video_id": "22222222-2222-2222-2222-222222222222",
"prediction_id": "pred_abc123",
"provider": "fal",
"model_id": "openai/sora-2",
"status": "processing",
"output_url": null,
"credits_used": 5
}
}
Starts async video generation and returns a canonical
video_id.
Poll GET /api/partner/v1/studio/videos/{videoId} for final state.
Idempotency
Send a uniqueIdempotency-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
{
"model_id": "bytedance/seedance-2.0",
"prompt": "Cinematic product reveal using @Image1 as the product style reference",
"reference_image_urls": ["https://example.com/product.jpg"],
"params": {
"duration_seconds": 5,
"aspect_ratio": "9:16",
"generate_audio": true
}
}
{
"ok": true,
"code": 202,
"message": "Video generation started",
"data": {
"video_id": "22222222-2222-2222-2222-222222222222",
"prediction_id": "pred_abc123",
"provider": "fal",
"model_id": "openai/sora-2",
"status": "processing",
"output_url": null,
"credits_used": 5
}
}
Error Responses
400 invalid_json- request body is not valid JSON401- authentication failed (missing/invalid/revoked token)402 subscription_required- active Creator/Professional/Business plan required403 tier_not_allowed- Scheduler tier cannot use Partner API402 insufficient_credits- buy a credit pack athttps://www.genviral.io/billing?tab=credits, then retry422 invalid_payload(includes unsupportedmodel_id)422 invalid_input500 generation_failed