> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genviral.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Studio Video

> Start async AI Studio video generation and return canonical `video_id` for polling.

Starts async video generation and returns a canonical `video_id`.

Poll `GET /api/partner/v1/studio/videos/{videoId}` for final state.

## Body Parameters

<ParamField body="model_id" type="string" required>
  Video model ID from [Get Studio Models](/api-reference/get-studio-models).
</ParamField>

<ParamField body="prompt" type="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.
</ParamField>

<ParamField body="speech_text" type="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.
</ParamField>

<ParamField body="voice_id" type="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.
</ParamField>

<ParamField body="image_url" type="string">
  Optional input image URL for image-to-video models.
</ParamField>

<ParamField body="video_url" type="string">
  Optional input video URL for video-to-video models.
</ParamField>

<ParamField body="audio_url" type="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.
</ParamField>

<ParamField body="reference_image_urls" type="string[]">
  Optional Seedance 2.0 reference images. Up to 9 images. Refer to them in the
  prompt as `@Image1`, `@Image2`, etc.
</ParamField>

<ParamField body="reference_video_urls" type="string[]">
  Optional Seedance 2.0 reference videos. Up to 3 videos. Refer to them in the
  prompt as `@Video1`, `@Video2`, etc.
</ParamField>

<ParamField body="reference_audio_urls" type="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.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Optional negative prompt.
</ParamField>

<ParamField body="params" type="object">
  Normalized video params. Supported keys: `resolution`, `duration_seconds`, `fps`, `aspect_ratio`, `generate_audio`.
</ParamField>

<ParamField body="raw_params" type="object">
  Optional model-specific passthrough params.
</ParamField>

## Example

<RequestExample>
  ```json theme={null}
  {
    "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
    }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

## 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`