First Frame Image - PictoryAI

This guide shows you how to use the firstFrameImageUrl field to control the starting frame of an AI-generated video clip. By providing an image URL, the AI model generates a video that begins from your image and transitions into the motion described in your prompt.

What You Will Learn

First Frame Control

Set a specific image as the starting frame of your AI video

Seamless Transitions

Create videos that begin from a known visual state

Creative Control

Combine first frame images with text prompts for precise results

Validation Rules

Understand when and how to use first frame images correctly

Before You Begin

Make sure you have:

A Pictory API key
Node.js or Python installed on your machine
Sufficient AI credits in your account
A publicly accessible image URL to use as the first frame
Familiarity with AI-generated background video clips

npm install axios

pip install requests

How It Works

When you provide firstFrameImageUrl in the aiVisual object:

The AI model receives your image as the starting point
The model generates a video clip that begins from this image
The video transitions from the static image into the motion described by your prompt (or auto-generated prompt from the story text)
The result is a video that feels like a natural extension of the provided image

firstFrameImageUrl is only available when background.type is "video". For image generation, use referenceImageUrl instead.

Configuration

Add firstFrameImageUrl to the aiVisual object with a valid image URL:

{
  "background": {
    "type": "video",
    "aiVisual": {
      "prompt": "Camera slowly zooms out to reveal a bustling city skyline",
      "model": "pixverse5.5",
      "videoDuration": "8s",
      "firstFrameImageUrl": "https://example.com/city-closeup.jpg"
    }
  }
}

firstFrameImageUrl cannot be used together with referenceImageUrls. Use one or the other, not both.

Examples

Example 1: Single Story Without Prompt

One scene with a story paragraph and a first frame image. The system splits the story into multiple scenes and auto-generates prompts. The first frame image controls the starting visual of the video.

import axios from "axios";

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

async function createFirstFrameAutoPrompt() {
  const response = await axios.post(
    `${API_BASE_URL}/v2/video/storyboard/render`,
    {
      videoName: "first-frame-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",
              videoDuration: "8s",
              firstFrameImageUrl: "https://example.com/starting-frame.jpg"
            }
          }
        }
      ]
    },
    { 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));
  }
}

createFirstFrameAutoPrompt();

import requests
import time

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

def create_first_frame_auto_prompt():
    response = requests.post(
        f'{API_BASE_URL}/v2/video/storyboard/render',
        json={
            'videoName': 'first-frame-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',
                            'videoDuration': '8s',
                            'firstFrameImageUrl': 'https://example.com/starting-frame.jpg'
                        }
                    }
                }
            ]
        },
        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_first_frame_auto_prompt()

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

import axios from "axios";

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

async function createFirstFrameCreativeDirection() {
  const response = await axios.post(
    `${API_BASE_URL}/v2/video/storyboard/render`,
    {
      videoName: "first-frame-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",
              videoDuration: "8s",
              firstFrameImageUrl: "https://example.com/starting-frame.jpg",
              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));
  }
}

createFirstFrameCreativeDirection();

import requests
import time

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

def create_first_frame_creative_direction():
    response = requests.post(
        f'{API_BASE_URL}/v2/video/storyboard/render',
        json={
            'videoName': 'first-frame-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',
                            'videoDuration': '8s',
                            'firstFrameImageUrl': 'https://example.com/starting-frame.jpg',
                            '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_first_frame_creative_direction()

Example 3: Multiple Scenes with Prompts

Three separate scenes, each with a one-sentence story, a scene-specific prompt, and its own first frame image.

import axios from "axios";

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

async function createFirstFrameScenePrompts() {
  const response = await axios.post(
    `${API_BASE_URL}/v2/video/storyboard/render`,
    {
      videoName: "first-frame-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",
              firstFrameImageUrl: "https://example.com/creator-at-desk.jpg",
              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",
              firstFrameImageUrl: "https://example.com/ai-workspace.jpg",
              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",
              firstFrameImageUrl: "https://example.com/professionals-presenting.jpg",
              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));
  }
}

createFirstFrameScenePrompts();

import requests
import time

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

def create_first_frame_scene_prompts():
    response = requests.post(
        f'{API_BASE_URL}/v2/video/storyboard/render',
        json={
            'videoName': 'first-frame-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', 'firstFrameImageUrl': 'https://example.com/creator-at-desk.jpg', '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', 'firstFrameImageUrl': 'https://example.com/ai-workspace.jpg', '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', 'firstFrameImageUrl': 'https://example.com/professionals-presenting.jpg', '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_first_frame_scene_prompts()

Example 4: Multiple Scenes Without Prompts

Three separate scenes, each with a one-sentence story and its own first frame image. No prompts are provided, so the system auto-generates a visual prompt from each scene’s story text.

import axios from "axios";

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

async function createFirstFrameAutoScenes() {
  const response = await axios.post(
    `${API_BASE_URL}/v2/video/storyboard/render`,
    {
      videoName: "first-frame-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", firstFrameImageUrl: "https://example.com/creator-at-desk.jpg" }
          }
        },
        {
          story: "AI-powered tools generate custom visuals from simple text prompts in minutes.",
          background: {
            type: "video",
            aiVisual: { model: "pixverse5.5", videoDuration: "5s", firstFrameImageUrl: "https://example.com/ai-workspace.jpg" }
          }
        },
        {
          story: "Professional-quality videos are now accessible to educators and marketers everywhere.",
          background: {
            type: "video",
            aiVisual: { model: "pixverse5.5", videoDuration: "5s", firstFrameImageUrl: "https://example.com/professionals-presenting.jpg" }
          }
        }
      ]
    },
    { 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));
  }
}

createFirstFrameAutoScenes();

import requests
import time

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

def create_first_frame_auto_scenes():
    response = requests.post(
        f'{API_BASE_URL}/v2/video/storyboard/render',
        json={
            'videoName': 'first-frame-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', 'firstFrameImageUrl': 'https://example.com/creator-at-desk.jpg'}}},
                {'story': 'AI-powered tools generate custom visuals from simple text prompts in minutes.', 'background': {'type': 'video', 'aiVisual': {'model': 'pixverse5.5', 'videoDuration': '5s', 'firstFrameImageUrl': 'https://example.com/ai-workspace.jpg'}}},
                {'story': 'Professional-quality videos are now accessible to educators and marketers everywhere.', 'background': {'type': 'video', 'aiVisual': {'model': 'pixverse5.5', 'videoDuration': '5s', 'firstFrameImageUrl': 'https://example.com/professionals-presenting.jpg'}}}
            ]
        },
        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_first_frame_auto_scenes()

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.

{
    "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 or Get Video Render Job API reference.

Best Practices

Choose the Right Image

Use high-quality, well-composed images as your first frame
Ensure the image resolution is appropriate for your video’s aspect ratio
Avoid images with heavy text overlays, as AI may distort them during animation
Use images that have natural elements the AI can animate (for example, clouds, water, people)

Write Prompts That Complement the Image

Your prompt should describe the motion and transition from the static image, not the image itself:

Good: “Camera slowly zooms out revealing the surrounding environment”
Poor: “A laptop on a desk” (describes what is already in the image)

The AI already has the image as context. Focus your prompt on what should happen next.

Ensure Image Accessibility

The image URL must be publicly accessible (no authentication required)
Use direct image URLs (not page URLs that contain images)
Supported formats include JPEG, PNG, and WebP

Troubleshooting

Error: firstFrameImageUrl Is Only Allowed When Type Is Video

Cause: firstFrameImageUrl is used with type: "image".Resolution:

Change type to "video" if you want to generate a video clip starting from your image
For image generation, use referenceImageUrl instead

Error: firstFrameImageUrl and referenceImageUrls Cannot Be Provided Together

Cause: Both firstFrameImageUrl and referenceImageUrls are provided in the same scene.Resolution:

Choose one approach: firstFrameImageUrl to control the starting frame, or referenceImageUrls to guide style
Remove the field you do not need

Generated Video Does Not Match the First Frame

Cause: The AI model may interpret the image differently depending on the prompt and model used.Resolution:

Write a prompt that describes the desired motion from the image, not the image itself
Try a different model for better image-to-video fidelity
Ensure the image URL is accessible and returns a valid image

Next Steps

Visual Continuity

Create seamless transitions between consecutive scenes

Reference Image for Images

Guide AI image generation with a reference image

Reference Images for Videos

Guide AI video generation with reference images

AI-Generated Video Clips

Learn the basics of AI video clip generation

API Reference

Render Storyboard Video

Direct video rendering with AI visuals

Create Storyboard Preview

Create preview before rendering

​What You Will Learn

First Frame Control

Seamless Transitions

Creative Control

Validation Rules

​Before You Begin

​How It Works

​Configuration

​Examples

​Example 1: Single Story Without Prompt

​Example 2: Single Story with Creative Direction

​Example 3: Multiple Scenes with Prompts

​Example 4: Multiple Scenes Without Prompts

​Tracking AI Credits Used

​Best Practices

​Troubleshooting

​Next Steps

Visual Continuity

Reference Image for Images

Reference Images for Videos

AI-Generated Video Clips

​API Reference

Render Storyboard Video

Create Storyboard Preview

What You Will Learn

Before You Begin

How It Works

Configuration

Examples

Example 1: Single Story Without Prompt

Example 2: Single Story with Creative Direction

Example 3: Multiple Scenes with Prompts

Example 4: Multiple Scenes Without Prompts

Tracking AI Credits Used

Best Practices

Troubleshooting

Next Steps

API Reference