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

# AI-Generated Scene Background Video Clips

> Generate AI video clips as scene backgrounds using models like Pixverse 5.5, Veo 3.1 Fast, and Veo 3.1

This guide shows you how to use AI-generated video clips as scene backgrounds. Instead of stock footage, generate unique motion video clips from text prompts using AI video models — each offering different quality levels, durations, and AI credit costs.

## What You Will Learn

<CardGroup cols={2}>
  <Card title="AI Video Generation" icon="film">
    Generate unique video clips as scene backgrounds
  </Card>

  <Card title="Video Models" icon="palette">
    Choose from Pixverse 5.5, Veo 3.1 Fast, and Veo 3.1
  </Card>

  <Card title="Duration Control" icon="clock">
    Configure clip duration from 4 to 10 seconds per model
  </Card>

  <Card title="AI Credit Costs" icon="bolt">
    Understand per-second credit costs for each model
  </Card>
</CardGroup>

## Before You Begin

Make sure you have:

* A [Pictory API key](https://app.pictory.ai/api-access)
* Node.js or Python installed on your machine
* Sufficient AI credits in your account (video generation costs more than image generation)
* Basic understanding of AI video generation concepts

<CodeGroup>
  ```bash npm theme={null}
  npm install axios
  ```

  ```bash pip theme={null}
  pip install requests
  ```
</CodeGroup>

## How It Works

When you set `background.type` to `"video"` and provide an `aiVisual` configuration, Pictory generates a unique AI video clip for the scene background:

1. **Prompt Processing** — Your text prompt (or auto-generated prompt from story text) describes the desired motion video
2. **Video Generation** — The chosen video model creates a unique clip of the specified duration
3. **Scene Integration** — The generated video clip is used as the scene background

<Note>
  AI video generation takes significantly longer than image generation and costs more AI credits. The credit cost is calculated **per second of video** generated. Plan for additional processing time and budget accordingly.
</Note>

## Configuration Reference

### Background Object

When using AI-generated video clips, set the `background` object on a scene as follows:

| Parameter  | Type   | Required | Description                                    |
| ---------- | ------ | -------- | ---------------------------------------------- |
| `type`     | string | Yes      | Must be `"video"` for AI-generated video clips |
| `aiVisual` | object | Yes      | AI video generation configuration (see below)  |

<Warning>
  **Mutually Exclusive:** The `background` object can only have **one** of `visualUrl`, `color`, or `aiVisual`. You cannot combine them in the same scene.
</Warning>

### `aiVisual` Parameters

| Parameter       | Type   | Required | Description                                                                                                                                                               |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`        | string | No       | Text description of the video to generate (max 500 characters). If omitted, a prompt is auto-generated from the scene's story text.                                       |
| `model`         | string | Yes      | The AI video model to use. See [Available Video Models](#available-video-models).                                                                                         |
| `videoDuration` | string | No       | Duration of the generated clip. Valid values depend on the model. See [Duration Options](#duration-options). If omitted, the model's default (shortest) duration is used. |

## Available Video Models

Each model has different quality, supported durations, aspect ratios, and per-second AI credit costs.

| Model ID      | Display Name | AI Credits (per second) | Best For                    |
| ------------- | ------------ | ----------------------- | --------------------------- |
| `pixverse5.5` | Pixverse 5.5 | 1.6                     | Reliable for basic motion   |
| `veo3.1_fast` | Veo 3.1 Fast | 10                      | Efficient cinematic quality |
| `veo3.1`      | Veo 3.1      | 20                      | Superior cinematic quality  |

### Duration Options

Each model supports specific clip durations. If `videoDuration` is omitted or invalid for the selected model, the first (shortest) duration is used as the default.

| Model         | Available Durations     | Default |
| ------------- | ----------------------- | ------- |
| `pixverse5.5` | `"5s"`, `"8s"`, `"10s"` | `"5s"`  |
| `veo3.1_fast` | `"4s"`, `"6s"`, `"8s"`  | `"4s"`  |
| `veo3.1`      | `"4s"`, `"6s"`, `"8s"`  | `"4s"`  |

### Supported Aspect Ratios

The video aspect ratio is determined by the `aspectRatio` property at the top level of the request. Different models support different aspect ratios:

| Model         | Supported Aspect Ratios |
| ------------- | ----------------------- |
| `pixverse5.5` | `16:9`, `9:16`, `1:1`   |
| `veo3.1_fast` | `16:9`, `9:16`          |
| `veo3.1`      | `16:9`, `9:16`          |

<Note>
  If the request's `aspectRatio` is not supported by the selected video model, the system automatically falls back to the model's first supported aspect ratio.
</Note>

### AI Credit Cost Calculator

AI credits for video generation are calculated as: **credits per second x duration in seconds**.

| Model         | 4s | 5s | 6s  | 8s   | 10s |
| ------------- | -- | -- | --- | ---- | --- |
| `pixverse5.5` | —  | 8  | —   | 12.8 | 16  |
| `veo3.1_fast` | 40 | —  | 60  | 80   | —   |
| `veo3.1`      | 80 | —  | 120 | 160  | —   |

<Tip>
  **Cost-Saving Strategy:**

  * Use `pixverse5.5` at `"5s"` (8 credits) for testing and drafts
  * Use shorter durations when possible — a 4s clip costs half of an 8s clip
  * Reserve `veo3.1` for final production where cinematic quality matters
</Tip>

## Examples

### Example 1: Single Story Without Prompt

One scene with a story paragraph. The system splits the story into multiple scenes using `createSceneOnEndOfSentence` and auto-generates a visual prompt for each scene from its story text.

<CodeGroup>
  ```javascript Node.js theme={null}
  import axios from "axios";

  const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
  const API_KEY = "YOUR_API_KEY";

  async function createVideoWithAutoPrompt() {
    const response = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "ai-video-auto-prompt",
        language: "en",
        backgroundMusic: { enabled: true, autoMusic: true, volume: 0.5 },
        voiceOver: {
          enabled: true,
          aiVoices: [{ speaker: "Jackson", speed: 100, amplificationLevel: 0 }]
        },
        scenes: [
          {
            story: "Every day, millions of content creators, educators, and marketers face the same challenge. They need professional-quality videos but do not have a production team. Hours are spent searching stock libraries for footage that almost fits. Days are lost waiting for design assets. AI-powered video creation changes everything. With a simple text prompt, you can generate custom visuals tailored to your exact narrative. No more settling for generic stock footage. Whether you are building an online course, launching a campaign, or growing your social media presence, AI visuals give you the power to create stunning content in minutes.",
            createSceneOnNewLine: true,
            createSceneOnEndOfSentence: true,
            background: {
              type: "video",
              aiVisual: {
                model: "pixverse5.5"
              }
            }
          }
        ]
      },
      { headers: { "Content-Type": "application/json", Authorization: API_KEY } }
    );

    const jobId = response.data.data.jobId;
    console.log("Job ID:", jobId);

    let jobCompleted = false;
    while (!jobCompleted) {
      const statusResponse = await axios.get(
        `${API_BASE_URL}/v1/jobs/${jobId}`,
        { headers: { Authorization: API_KEY } }
      );
      const status = statusResponse.data.data.status;
      console.log("Status:", status);
      if (status === "completed") {
        jobCompleted = true;
        console.log("Video URL:", statusResponse.data.data.videoURL);
      } else if (status === "failed") {
        throw new Error("Failed: " + JSON.stringify(statusResponse.data));
      }
      await new Promise((resolve) => setTimeout(resolve, 15000));
    }
  }

  createVideoWithAutoPrompt();
  ```

  ```python Python theme={null}
  import requests
  import time

  API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
  API_KEY = 'YOUR_API_KEY'

  def create_video_with_auto_prompt():
      response = requests.post(
          f'{API_BASE_URL}/v2/video/storyboard/render',
          json={
              'videoName': 'ai-video-auto-prompt',
              'language': 'en',
              'backgroundMusic': {'enabled': True, 'autoMusic': True, 'volume': 0.5},
              'voiceOver': {
                  'enabled': True,
                  'aiVoices': [{'speaker': 'Jackson', 'speed': 100, 'amplificationLevel': 0}]
              },
              'scenes': [
                  {
                      'story': 'Every day, millions of content creators, educators, and marketers face the same challenge. They need professional-quality videos but do not have a production team. Hours are spent searching stock libraries for footage that almost fits. Days are lost waiting for design assets. AI-powered video creation changes everything. With a simple text prompt, you can generate custom visuals tailored to your exact narrative. No more settling for generic stock footage. Whether you are building an online course, launching a campaign, or growing your social media presence, AI visuals give you the power to create stunning content in minutes.',
                      'createSceneOnNewLine': True,
                      'createSceneOnEndOfSentence': True,
                      'background': {
                          'type': 'video',
                          'aiVisual': {
                              'model': 'pixverse5.5'
                          }
                      }
                  }
              ]
          },
          headers={'Content-Type': 'application/json', 'Authorization': API_KEY},
      )
      response.raise_for_status()

      job_id = response.json()['data']['jobId']
      print(f"Job ID: {job_id}")

      job_completed = False
      while not job_completed:
          status_response = requests.get(
              f'{API_BASE_URL}/v1/jobs/{job_id}',
              headers={'Authorization': API_KEY},
          )
          status_response.raise_for_status()
          status = status_response.json()['data']['status']
          print(f"Status: {status}")
          if status == 'completed':
              job_completed = True
              print(f"Video URL: {status_response.json()['data']['videoURL']}")
          elif status == 'failed':
              raise Exception(f"Failed: {status_response.json()}")
          time.sleep(15)

  if __name__ == '__main__':
      create_video_with_auto_prompt()
  ```
</CodeGroup>

### Example 2: Single Story with Creative Direction

Same as Example 1, but with a `prompt` that acts as **creative direction** for the entire video. Since the story is split into multiple scenes, the prompt guides the overall visual tone rather than describing a specific scene. A good creative direction prompt follows this structure: \[Action/Movement] + \[Scene/Environment] + \[Camera Technique] + \[Visual Style].

<CodeGroup>
  ```javascript Node.js theme={null}
  import axios from "axios";

  const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
  const API_KEY = "YOUR_API_KEY";

  async function createVideoWithCreativeDirection() {
    const response = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "ai-video-creative-direction",
        language: "en",
        backgroundMusic: { enabled: true, autoMusic: true, volume: 0.5 },
        voiceOver: {
          enabled: true,
          aiVoices: [{ speaker: "Jackson", speed: 100, amplificationLevel: 0 }]
        },
        scenes: [
          {
            story: "Every day, millions of content creators, educators, and marketers face the same challenge. They need professional-quality videos but do not have a production team. Hours are spent searching stock libraries for footage that almost fits. Days are lost waiting for design assets. AI-powered video creation changes everything. With a simple text prompt, you can generate custom visuals tailored to your exact narrative. No more settling for generic stock footage. Whether you are building an online course, launching a campaign, or growing your social media presence, AI visuals give you the power to create stunning content in minutes.",
            createSceneOnNewLine: true,
            createSceneOnEndOfSentence: true,
            background: {
              type: "video",
              aiVisual: {
                model: "pixverse5.5",
                prompt: "Smooth cinematic tracking shots in modern creative workspaces with warm golden-hour lighting and shallow depth of field"
              }
            }
          }
        ]
      },
      { headers: { "Content-Type": "application/json", Authorization: API_KEY } }
    );

    const jobId = response.data.data.jobId;
    console.log("Job ID:", jobId);

    let jobCompleted = false;
    while (!jobCompleted) {
      const statusResponse = await axios.get(
        `${API_BASE_URL}/v1/jobs/${jobId}`,
        { headers: { Authorization: API_KEY } }
      );
      const status = statusResponse.data.data.status;
      console.log("Status:", status);
      if (status === "completed") {
        jobCompleted = true;
        console.log("Video URL:", statusResponse.data.data.videoURL);
      } else if (status === "failed") {
        throw new Error("Failed: " + JSON.stringify(statusResponse.data));
      }
      await new Promise((resolve) => setTimeout(resolve, 15000));
    }
  }

  createVideoWithCreativeDirection();
  ```

  ```python Python theme={null}
  import requests
  import time

  API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
  API_KEY = 'YOUR_API_KEY'

  def create_video_with_creative_direction():
      response = requests.post(
          f'{API_BASE_URL}/v2/video/storyboard/render',
          json={
              'videoName': 'ai-video-creative-direction',
              'language': 'en',
              'backgroundMusic': {'enabled': True, 'autoMusic': True, 'volume': 0.5},
              'voiceOver': {
                  'enabled': True,
                  'aiVoices': [{'speaker': 'Jackson', 'speed': 100, 'amplificationLevel': 0}]
              },
              'scenes': [
                  {
                      'story': 'Every day, millions of content creators, educators, and marketers face the same challenge. They need professional-quality videos but do not have a production team. Hours are spent searching stock libraries for footage that almost fits. Days are lost waiting for design assets. AI-powered video creation changes everything. With a simple text prompt, you can generate custom visuals tailored to your exact narrative. No more settling for generic stock footage. Whether you are building an online course, launching a campaign, or growing your social media presence, AI visuals give you the power to create stunning content in minutes.',
                      'createSceneOnNewLine': True,
                      'createSceneOnEndOfSentence': True,
                      'background': {
                          'type': 'video',
                          'aiVisual': {
                              'model': 'pixverse5.5',
                              'prompt': 'Smooth cinematic tracking shots in modern creative workspaces with warm golden-hour lighting and shallow depth of field'
                          }
                      }
                  }
              ]
          },
          headers={'Content-Type': 'application/json', 'Authorization': API_KEY},
      )
      response.raise_for_status()

      job_id = response.json()['data']['jobId']
      print(f"Job ID: {job_id}")

      job_completed = False
      while not job_completed:
          status_response = requests.get(
              f'{API_BASE_URL}/v1/jobs/{job_id}',
              headers={'Authorization': API_KEY},
          )
          status_response.raise_for_status()
          status = status_response.json()['data']['status']
          print(f"Status: {status}")
          if status == 'completed':
              job_completed = True
              print(f"Video URL: {status_response.json()['data']['videoURL']}")
          elif status == 'failed':
              raise Exception(f"Failed: {status_response.json()}")
          time.sleep(15)

  if __name__ == '__main__':
      create_video_with_creative_direction()
  ```
</CodeGroup>

### Example 3: Multiple Scenes with Prompts

Three separate scenes, each with a one-sentence story and a scene-specific prompt. The prompt directly describes the visual for that scene.

<CodeGroup>
  ```javascript Node.js theme={null}
  import axios from "axios";

  const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
  const API_KEY = "YOUR_API_KEY";

  async function createVideoWithScenePrompts() {
    const response = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "ai-video-scene-prompts",
        language: "en",
        backgroundMusic: { enabled: true, autoMusic: true, volume: 0.5 },
        voiceOver: {
          enabled: true,
          aiVoices: [{ speaker: "Jackson", speed: 100, amplificationLevel: 0 }]
        },
        scenes: [
          {
            story: "Content creators struggle to find the perfect visuals for their videos.",
            background: {
              type: "video",
              aiVisual: {
                model: "pixverse5.5",
                videoDuration: "5s",
                prompt: "A frustrated creator scrolling through endless stock footage on a laptop in a dimly lit room"
              }
            }
          },
          {
            story: "AI-powered tools generate custom visuals from simple text prompts in minutes.",
            background: {
              type: "video",
              aiVisual: {
                model: "pixverse5.5",
                videoDuration: "5s",
                prompt: "A bright modern workspace with AI-generated visuals appearing on a large monitor"
              }
            }
          },
          {
            story: "Professional-quality videos are now accessible to educators and marketers everywhere.",
            background: {
              type: "video",
              aiVisual: {
                model: "pixverse5.5",
                videoDuration: "5s",
                prompt: "Diverse professionals confidently presenting polished video content on various devices"
              }
            }
          }
        ]
      },
      { headers: { "Content-Type": "application/json", Authorization: API_KEY } }
    );

    const jobId = response.data.data.jobId;
    console.log("Job ID:", jobId);

    let jobCompleted = false;
    while (!jobCompleted) {
      const statusResponse = await axios.get(
        `${API_BASE_URL}/v1/jobs/${jobId}`,
        { headers: { Authorization: API_KEY } }
      );
      const status = statusResponse.data.data.status;
      console.log("Status:", status);
      if (status === "completed") {
        jobCompleted = true;
        console.log("Video URL:", statusResponse.data.data.videoURL);
      } else if (status === "failed") {
        throw new Error("Failed: " + JSON.stringify(statusResponse.data));
      }
      await new Promise((resolve) => setTimeout(resolve, 15000));
    }
  }

  createVideoWithScenePrompts();
  ```

  ```python Python theme={null}
  import requests
  import time

  API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
  API_KEY = 'YOUR_API_KEY'

  def create_video_with_scene_prompts():
      response = requests.post(
          f'{API_BASE_URL}/v2/video/storyboard/render',
          json={
              'videoName': 'ai-video-scene-prompts',
              'language': 'en',
              'backgroundMusic': {'enabled': True, 'autoMusic': True, 'volume': 0.5},
              'voiceOver': {
                  'enabled': True,
                  'aiVoices': [{'speaker': 'Jackson', 'speed': 100, 'amplificationLevel': 0}]
              },
              'scenes': [
                  {
                      'story': 'Content creators struggle to find the perfect visuals for their videos.',
                      'background': {
                          'type': 'video',
                          'aiVisual': {
                              'model': 'pixverse5.5',
                              'videoDuration': '5s',
                              'prompt': 'A frustrated creator scrolling through endless stock footage on a laptop in a dimly lit room'
                          }
                      }
                  },
                  {
                      'story': 'AI-powered tools generate custom visuals from simple text prompts in minutes.',
                      'background': {
                          'type': 'video',
                          'aiVisual': {
                              'model': 'pixverse5.5',
                              'videoDuration': '5s',
                              'prompt': 'A bright modern workspace with AI-generated visuals appearing on a large monitor'
                          }
                      }
                  },
                  {
                      'story': 'Professional-quality videos are now accessible to educators and marketers everywhere.',
                      'background': {
                          'type': 'video',
                          'aiVisual': {
                              'model': 'pixverse5.5',
                              'videoDuration': '5s',
                              'prompt': 'Diverse professionals confidently presenting polished video content on various devices'
                          }
                      }
                  }
              ]
          },
          headers={'Content-Type': 'application/json', 'Authorization': API_KEY},
      )
      response.raise_for_status()

      job_id = response.json()['data']['jobId']
      print(f"Job ID: {job_id}")

      job_completed = False
      while not job_completed:
          status_response = requests.get(
              f'{API_BASE_URL}/v1/jobs/{job_id}',
              headers={'Authorization': API_KEY},
          )
          status_response.raise_for_status()
          status = status_response.json()['data']['status']
          print(f"Status: {status}")
          if status == 'completed':
              job_completed = True
              print(f"Video URL: {status_response.json()['data']['videoURL']}")
          elif status == 'failed':
              raise Exception(f"Failed: {status_response.json()}")
          time.sleep(15)

  if __name__ == '__main__':
      create_video_with_scene_prompts()
  ```
</CodeGroup>

### Example 4: Multiple Scenes Without Prompts

Three separate scenes, each with a one-sentence story. No prompts are provided, so the system auto-generates a visual prompt from each scene's story text.

<CodeGroup>
  ```javascript Node.js theme={null}
  import axios from "axios";

  const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
  const API_KEY = "YOUR_API_KEY";

  async function createVideoAutoScenes() {
    const response = await axios.post(
      `${API_BASE_URL}/v2/video/storyboard/render`,
      {
        videoName: "ai-video-auto-scenes",
        language: "en",
        backgroundMusic: { enabled: true, autoMusic: true, volume: 0.5 },
        voiceOver: {
          enabled: true,
          aiVoices: [{ speaker: "Jackson", speed: 100, amplificationLevel: 0 }]
        },
        scenes: [
          {
            story: "Content creators struggle to find the perfect visuals for their videos.",
            background: {
              type: "video",
              aiVisual: {
                model: "pixverse5.5",
                videoDuration: "5s"
              }
            }
          },
          {
            story: "AI-powered tools generate custom visuals from simple text prompts in minutes.",
            background: {
              type: "video",
              aiVisual: {
                model: "pixverse5.5",
                videoDuration: "5s"
              }
            }
          },
          {
            story: "Professional-quality videos are now accessible to educators and marketers everywhere.",
            background: {
              type: "video",
              aiVisual: {
                model: "pixverse5.5",
                videoDuration: "5s"
              }
            }
          }
        ]
      },
      { headers: { "Content-Type": "application/json", Authorization: API_KEY } }
    );

    const jobId = response.data.data.jobId;
    console.log("Job ID:", jobId);

    let jobCompleted = false;
    while (!jobCompleted) {
      const statusResponse = await axios.get(
        `${API_BASE_URL}/v1/jobs/${jobId}`,
        { headers: { Authorization: API_KEY } }
      );
      const status = statusResponse.data.data.status;
      console.log("Status:", status);
      if (status === "completed") {
        jobCompleted = true;
        console.log("Video URL:", statusResponse.data.data.videoURL);
      } else if (status === "failed") {
        throw new Error("Failed: " + JSON.stringify(statusResponse.data));
      }
      await new Promise((resolve) => setTimeout(resolve, 15000));
    }
  }

  createVideoAutoScenes();
  ```

  ```python Python theme={null}
  import requests
  import time

  API_BASE_URL = 'https://api.pictory.ai/pictoryapis'
  API_KEY = 'YOUR_API_KEY'

  def create_video_auto_scenes():
      response = requests.post(
          f'{API_BASE_URL}/v2/video/storyboard/render',
          json={
              'videoName': 'ai-video-auto-scenes',
              'language': 'en',
              'backgroundMusic': {'enabled': True, 'autoMusic': True, 'volume': 0.5},
              'voiceOver': {
                  'enabled': True,
                  'aiVoices': [{'speaker': 'Jackson', 'speed': 100, 'amplificationLevel': 0}]
              },
              'scenes': [
                  {
                      'story': 'Content creators struggle to find the perfect visuals for their videos.',
                      'background': {
                          'type': 'video',
                          'aiVisual': {
                              'model': 'pixverse5.5',
                              'videoDuration': '5s'
                          }
                      }
                  },
                  {
                      'story': 'AI-powered tools generate custom visuals from simple text prompts in minutes.',
                      'background': {
                          'type': 'video',
                          'aiVisual': {
                              'model': 'pixverse5.5',
                              'videoDuration': '5s'
                          }
                      }
                  },
                  {
                      'story': 'Professional-quality videos are now accessible to educators and marketers everywhere.',
                      'background': {
                          'type': 'video',
                          'aiVisual': {
                              'model': 'pixverse5.5',
                              'videoDuration': '5s'
                          }
                      }
                  }
              ]
          },
          headers={'Content-Type': 'application/json', 'Authorization': API_KEY},
      )
      response.raise_for_status()

      job_id = response.json()['data']['jobId']
      print(f"Job ID: {job_id}")

      job_completed = False
      while not job_completed:
          status_response = requests.get(
              f'{API_BASE_URL}/v1/jobs/{job_id}',
              headers={'Authorization': API_KEY},
          )
          status_response.raise_for_status()
          status = status_response.json()['data']['status']
          print(f"Status: {status}")
          if status == 'completed':
              job_completed = True
              print(f"Video URL: {status_response.json()['data']['videoURL']}")
          elif status == 'failed':
              raise Exception(f"Failed: {status_response.json()}")
          time.sleep(15)

  if __name__ == '__main__':
      create_video_auto_scenes()
  ```
</CodeGroup>

***

## Tracking AI Credits Used

When your video includes AI-generated visuals, the job response includes an `aiCreditsUsed` field that reports the total AI credits consumed across all scenes. This field is present only when at least one scene used `aiVisual` configuration.

```json theme={null}
{
    "job_id": "a1d36612-326d-4b81-aece-411f8aed4c70",
    "success": true,
    "data": {
        "status": "completed",
        "aiCreditsUsed": 48
    }
}
```

Use this value to track credit consumption and manage your AI credit budget. For detailed job response documentation, refer to the [Get Storyboard Preview Job](/api-reference/jobs/get-storyboard-preview-job-by-id) or [Get Video Render Job](/api-reference/jobs/get-video-render-job-by-id) API reference.

***

## Best Practices

<AccordionGroup>
  <Accordion title="Write Effective Video Prompts">
    Video prompts should describe **motion and action**, not just a static scene:

    * **Include movement:** "camera slowly panning across", "particles flowing", "waves crashing"
    * **Describe transitions:** "sunrise gradually illuminating", "zoom into details"
    * **Be specific about motion:** "cars driving through city streets" vs. just "city street"
    * **Keep under 500 characters:** Focused prompts produce better results

    **Good:** "Aerial drone shot slowly flying over a tropical coastline with turquoise waves rolling onto white sand"

    **Poor:** "Beach scene"
  </Accordion>

  <Accordion title="Choose the Right Model and Duration">
    | Scenario             | Recommended Model | Duration | Total Cost   |
    | -------------------- | ----------------- | -------- | ------------ |
    | Testing & drafts     | `pixverse5.5`     | `"5s"`   | 8 credits    |
    | General content      | `pixverse5.5`     | `"8s"`   | 12.8 credits |
    | Professional quality | `veo3.1_fast`     | `"6s"`   | 60 credits   |
    | Premium cinematic    | `veo3.1`          | `"8s"`   | 160 credits  |

    Start with `pixverse5.5` for iteration, then switch to `veo3.1_fast` or `veo3.1` for production.
  </Accordion>

  <Accordion title="Manage AI Credit Budget">
    Video generation can consume credits quickly. Plan your budget:

    * Use **shorter durations** when possible — 4s is often enough for a single scene
    * Use `pixverse5.5` for scenes where basic motion is sufficient
    * Reserve `veo3.1` for hero scenes that need premium quality
    * Mix AI video clips with AI images or stock visuals across scenes to manage costs
  </Accordion>

  <Accordion title="Plan for Processing Time">
    AI video generation takes significantly longer than image generation:

    * `pixverse5.5`: Fastest video generation
    * `veo3.1_fast`: Moderate processing time
    * `veo3.1`: Longest processing time but highest quality
    * Multiple scenes with AI video clips will multiply total processing time
    * Consider using AI video for key scenes only
  </Accordion>

  <Accordion title="Check Aspect Ratio Compatibility">
    Not all models support all aspect ratios:

    * `pixverse5.5` supports `16:9`, `9:16`, `1:1`
    * `veo3.1_fast` and `veo3.1` only support `16:9` and `9:16`
    * If your video uses `1:1` aspect ratio, use `pixverse5.5`
    * The system auto-corrects unsupported aspect ratios to the model's default
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Generated Video Does Not Show Expected Motion">
    * Add motion-specific language to your prompt: "slowly panning", "zooming in", "flowing"
    * Avoid static descriptions — describe what is happening, not just what is there
    * Try a higher-quality model for more nuanced motion rendering
  </Accordion>

  <Accordion title="Error: Invalid videoDuration for model">
    Each model has specific valid durations:

    * `pixverse5.5`: `"5s"`, `"8s"`, `"10s"`
    * `veo3.1_fast`: `"4s"`, `"6s"`, `"8s"`
    * `veo3.1`: `"4s"`, `"6s"`, `"8s"`

    Make sure you use a duration supported by your selected model.
  </Accordion>

  <Accordion title="Error: Invalid background configuration">
    ```javascript theme={null}
    // Correct
    background: {
      type: "video",
      aiVisual: {
        model: "pixverse5.5",
        videoDuration: "5s"
      }
    }

    // Wrong — type must be "video" for video models
    background: {
      type: "image",
      aiVisual: {
        model: "pixverse5.5",
        videoDuration: "5s"
      }
    }

    // Wrong — missing type
    background: {
      aiVisual: {
        model: "veo3.1",
        videoDuration: "6s"
      }
    }

    // Wrong — mixing background types
    background: {
      type: "video",
      visualUrl: "https://...",
      aiVisual: { model: "pixverse5.5" }
    }
    ```
  </Accordion>

  <Accordion title="Error: Insufficient AI credits">
    Video generation costs AI credits per second. Check your balance:

    * A `veo3.1` clip at `"8s"` costs **160 credits** per scene
    * Switch to `pixverse5.5` at `"5s"` (8 credits) for budget-friendly generation
    * Reduce `videoDuration` to lower the cost
  </Accordion>

  <Accordion title="Unsupported aspect ratio warning">
    If you specify an aspect ratio not supported by the video model, the system automatically falls back to the model's default:

    * `veo3.1` / `veo3.1_fast` only support `16:9` and `9:16`
    * Use `pixverse5.5` for `16:9`, `9:16`, and `1:1` aspect ratios
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="AI-Generated Background Images" icon="image" href="/guides/ai-generated-visuals/background-images">
    Use AI-generated images as scene backgrounds
  </Card>

  <Card title="AI Voice-Over" icon="microphone" href="/guides/text-to-video/ai-voiceover">
    Add professional narration to your videos
  </Card>

  <Card title="Brand Settings" icon="palette" href="/guides/branding-customization/brand-settings">
    Apply consistent branding automatically
  </Card>

  <Card title="Background Music" icon="music" href="/guides/advanced-features/background-music">
    Add music to complement your visuals
  </Card>
</CardGroup>

## API Reference

<CardGroup cols={2}>
  <Card title="Render Storyboard Video" icon="video" href="/api-reference/videos/render-storyboard-video">
    Direct video rendering with AI visuals
  </Card>

  <Card title="Create Storyboard Preview" icon="eye" href="/api-reference/videos/create-storyboard-preview">
    Create preview before rendering
  </Card>

  <Card title="Get Storyboard Preview Job" icon="clock" href="/api-reference/jobs/get-storyboard-preview-job-by-id">
    Monitor storyboard creation progress
  </Card>

  <Card title="Search Media" icon="images" href="/api-reference/media-management/search-media">
    Search stock visuals as alternative to AI
  </Card>
</CardGroup>
