Skip to main content
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.

​
Body Parameters

​
model_id
string
required
Video model ID from Get Studio Models.
​
prompt
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.
​
speech_text
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.
​
voice_id
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.
​
image_url
string
Optional input image URL for image-to-video models.
​
video_url
string
Optional input video URL for video-to-video models.
​
audio_url
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.
​
reference_image_urls
string[]
Optional Seedance 2.0 reference images. Up to 9 images. Refer to them in the prompt as @Image1, @Image2, etc.
​
reference_video_urls
string[]
Optional Seedance 2.0 reference videos. Up to 3 videos. Refer to them in the prompt as @Video1, @Video2, etc.
​
reference_audio_urls
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.
​
negative_prompt
string
Optional negative prompt.
​
params
object
Normalized video params. Supported keys: resolution, duration_seconds, fps, aspect_ratio, generate_audio.
​
raw_params
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 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