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

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

<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
* `402 insufficient_credits` - buy a credit pack at `https://www.genviral.io/billing?tab=credits`, then retry
* `422 invalid_payload` (includes unsupported `model_id`)
* `422 invalid_input`
* `500 generation_failed`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.