Reference Image for AI Images

This guide shows you how to use the referenceImageUrl field to guide AI image generation with a reference image. By providing a reference, you can influence the style, composition, and visual tone of the generated image while still using a text prompt for the subject matter.

What You Will Learn

Style Guidance

Use a reference image to guide the visual style of AI-generated images

Brand Consistency

Maintain a consistent look across scenes using brand reference images

Composition Control

Influence the layout and composition of generated images

Validation Rules

Understand when and how to use reference 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 a reference
Familiarity with AI-generated background images

npm install axios

pip install requests

How It Works

When you provide referenceImageUrl in the aiVisual object:

The AI model analyzes the reference image for style, color palette, composition, and visual tone
Your text prompt describes the subject matter and content to generate
The model combines the style influence from the reference image with the content from your prompt
The result is an image that matches your prompt’s subject matter while adopting visual characteristics from the reference

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

Configuration

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

{
  "background": {
    "type": "image",
    "aiVisual": {
      "prompt": "A modern workspace with natural lighting and indoor plants",
      "model": "seedream3.0",
      "mediaStyle": "photorealistic",
      "referenceImageUrl": "https://example.com/brand-style-reference.jpg"
    }
  }
}

Examples

Example 1: Single Story Without Prompt

One scene with a story paragraph and a reference image to guide style. The system splits the story into multiple scenes and auto-generates prompts. The reference image influences the visual style of all generated images.

import axios from "axios";

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

async function createReferenceImageAutoPrompt() {
  const response = await axios.post(
    `${API_BASE_URL}/v2/video/storyboard/render`,
    {
      videoName: "reference-image-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: "image",
            aiVisual: {
              model: "nanobanana",
              mediaStyle: "photorealistic",
              referenceImageUrl: "https://example.com/brand-style-reference.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, 10000));
  }
}

createReferenceImageAutoPrompt();

import requests
import time

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

def create_reference_image_auto_prompt():
    response = requests.post(
        f'{API_BASE_URL}/v2/video/storyboard/render',
        json={
            'videoName': 'reference-image-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': 'image', 'aiVisual': {'model': 'nanobanana', 'mediaStyle': 'photorealistic', 'referenceImageUrl': 'https://example.com/brand-style-reference.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(10)

if __name__ == '__main__':
    create_reference_image_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 createReferenceImageCreativeDirection() {
  const response = await axios.post(
    `${API_BASE_URL}/v2/video/storyboard/render`,
    {
      videoName: "reference-image-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: "image",
            aiVisual: {
              model: "nanobanana",
              mediaStyle: "photorealistic",
              referenceImageUrl: "https://example.com/brand-style-reference.jpg",
              prompt: "Wide-angle establishing shots of diverse professionals in bright, airy coworking spaces with large windows and natural daylight"
            }
          }
        }
      ]
    },
    { 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, 10000));
  }
}

createReferenceImageCreativeDirection();

import requests
import time

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

def create_reference_image_creative_direction():
    response = requests.post(
        f'{API_BASE_URL}/v2/video/storyboard/render',
        json={
            'videoName': 'reference-image-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': 'image', 'aiVisual': {'model': 'nanobanana', 'mediaStyle': 'photorealistic', 'referenceImageUrl': 'https://example.com/brand-style-reference.jpg', 'prompt': 'Wide-angle establishing shots of diverse professionals in bright, airy coworking spaces with large windows and natural daylight'}}
                }
            ]
        },
        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(10)

if __name__ == '__main__':
    create_reference_image_creative_direction()

Example 3: Multiple Scenes with Prompts

Three separate scenes, each with a one-sentence story, a scene-specific prompt, and a reference image to guide the visual style.

import axios from "axios";

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

async function createReferenceImageScenePrompts() {
  const response = await axios.post(
    `${API_BASE_URL}/v2/video/storyboard/render`,
    {
      videoName: "reference-image-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: "image",
            aiVisual: {
              model: "nanobanana",
              mediaStyle: "photorealistic",
              referenceImageUrl: "https://example.com/brand-style-reference.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: "image",
            aiVisual: {
              model: "nanobanana",
              mediaStyle: "photorealistic",
              referenceImageUrl: "https://example.com/brand-style-reference.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: "image",
            aiVisual: {
              model: "nanobanana",
              mediaStyle: "photorealistic",
              referenceImageUrl: "https://example.com/brand-style-reference.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, 10000));
  }
}

createReferenceImageScenePrompts();

import requests
import time

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

def create_reference_image_scene_prompts():
    response = requests.post(
        f'{API_BASE_URL}/v2/video/storyboard/render',
        json={
            'videoName': 'reference-image-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': 'image', 'aiVisual': {'model': 'nanobanana', 'mediaStyle': 'photorealistic', 'referenceImageUrl': 'https://example.com/brand-style-reference.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': 'image', 'aiVisual': {'model': 'nanobanana', 'mediaStyle': 'photorealistic', 'referenceImageUrl': 'https://example.com/brand-style-reference.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': 'image', 'aiVisual': {'model': 'nanobanana', 'mediaStyle': 'photorealistic', 'referenceImageUrl': 'https://example.com/brand-style-reference.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(10)

if __name__ == '__main__':
    create_reference_image_scene_prompts()

Example 4: Multiple Scenes Without Prompts

Three separate scenes, each with a one-sentence story and a reference 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 createReferenceImageAutoScenes() {
  const response = await axios.post(
    `${API_BASE_URL}/v2/video/storyboard/render`,
    {
      videoName: "reference-image-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: "image", aiVisual: { model: "nanobanana", mediaStyle: "photorealistic", referenceImageUrl: "https://example.com/brand-style-reference.jpg" } }
        },
        {
          story: "AI-powered tools generate custom visuals from simple text prompts in minutes.",
          background: { type: "image", aiVisual: { model: "nanobanana", mediaStyle: "photorealistic", referenceImageUrl: "https://example.com/brand-style-reference.jpg" } }
        },
        {
          story: "Professional-quality videos are now accessible to educators and marketers everywhere.",
          background: { type: "image", aiVisual: { model: "nanobanana", mediaStyle: "photorealistic", referenceImageUrl: "https://example.com/brand-style-reference.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, 10000));
  }
}

createReferenceImageAutoScenes();

import requests
import time

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

def create_reference_image_auto_scenes():
    response = requests.post(
        f'{API_BASE_URL}/v2/video/storyboard/render',
        json={
            'videoName': 'reference-image-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': 'image', 'aiVisual': {'model': 'nanobanana', 'mediaStyle': 'photorealistic', 'referenceImageUrl': 'https://example.com/brand-style-reference.jpg'}}},
                {'story': 'AI-powered tools generate custom visuals from simple text prompts in minutes.', 'background': {'type': 'image', 'aiVisual': {'model': 'nanobanana', 'mediaStyle': 'photorealistic', 'referenceImageUrl': 'https://example.com/brand-style-reference.jpg'}}},
                {'story': 'Professional-quality videos are now accessible to educators and marketers everywhere.', 'background': {'type': 'image', 'aiVisual': {'model': 'nanobanana', 'mediaStyle': 'photorealistic', 'referenceImageUrl': 'https://example.com/brand-style-reference.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(10)

if __name__ == '__main__':
    create_reference_image_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": 24
    }
}

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 Effective Reference Images

Use images with clear style characteristics (color palette, lighting, mood)
Avoid overly busy or cluttered reference images
The reference image does not need to match the subject of your prompt; it guides style, not content
High-quality reference images produce better style transfer results

Combine with Media Styles

You can use referenceImageUrl alongside mediaStyle for layered control:

mediaStyle sets the broad visual category (photorealistic, artistic, cartoon, etc.)
referenceImageUrl provides specific style nuances within that category

{
  "aiVisual": {
    "prompt": "Modern office building exterior",
    "model": "nanobanana",
    "mediaStyle": "minimalist",
    "referenceImageUrl": "https://example.com/clean-architecture.jpg"
  }
}

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: referenceImageUrl Is Only Allowed When Type Is Image

Cause: referenceImageUrl is used with type: "video".Resolution:

Change type to "image" if you want to generate AI images
For video generation, use firstFrameImageUrl or referenceImageUrls instead

Generated Image Does Not Reflect the Reference Style

Cause: The AI model may weigh the text prompt more heavily than the reference image, or the reference image style characteristics may be subtle.Resolution:

Use a reference image with strong, distinctive style characteristics
Try a higher-quality model like nanobanana or nanobanana-pro for better style adherence
Simplify your text prompt to give the reference image more influence

Next Steps

Visual Continuity

Create seamless transitions between consecutive scenes

First Frame Image

Control the starting frame of AI-generated video clips

Reference Images for Videos

Guide AI video generation with reference images

AI-Generated Background Images

Learn the basics of AI image generation

API Reference

Render Storyboard Video

Direct video rendering with AI visuals

Create Storyboard Preview

Create preview before rendering

​What You Will Learn

Style Guidance

Brand Consistency

Composition 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

First Frame Image

Reference Images for Videos

AI-Generated Background Images

​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