Skip to main content
POST
/
api
/
partner
/
v1
/
studio
/
videos
/
generate
{
  "model_id": "openai/sora-2",
  "prompt": "A drone shot over neon city streets at night",
  "params": {
    "duration_seconds": 8,
    "aspect_ratio": "16:9"
  }
}

{
  "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": 16
  }
}
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 main generation prompt.
​
speech_text
string
Optional speech script (for talking/lipsync model flows).
​
voice_id
string
Optional voice identifier used with speech_text.
​
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. Some models can run with audio/video inputs and no text prompt.
​
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": "openai/sora-2",
  "prompt": "A drone shot over neon city streets at night",
  "params": {
    "duration_seconds": 8,
    "aspect_ratio": "16:9"
  }
}

{
  "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": 16
  }
}

​
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