Skip to main content

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.

This guide shows you how to generate an AI image using both a text prompt and a reference image. The reference image provides visual context that guides the AI model, allowing you to create variations, apply transformations, or produce new compositions inspired by the original.

​
What You Will Build

Reference-Guided Generation

Use an existing image to guide the AI output

Creative Variations

Generate new images that draw from a source composition

Subject Replacement

Replace or modify subjects while preserving scene context

Style Transfer

Apply different visual styles to referenced content

​
Before You Begin

Make sure you have:
  • A Pictory API key (get one here)
  • Node.js or Python installed on your machine
  • The required packages installed
  • A publicly accessible URL for your reference image
npm install axios

​
Step-by-Step Guide

​
Step 1: Set Up Your Request

Prepare your API credentials, the reference image URL, and the prompt that describes the desired transformation or output. 
import axios from "axios";

const API_BASE_URL = "https://api.pictory.ai/pictoryapis";
const API_KEY = "YOUR_API_KEY"; // Replace with your actual API key

// Image generation with reference image
const imageRequest = {
  prompt: "Replace the dog with a white cat sitting in the same position on the park bench in the referenced image",
  model: "seedream3.0",
  aspectRatio: "16:9",
  style: "photorealistic",
  referenceImageUrl: "https://example.com/images/park-bench-scene.png"
};
The referenceImageUrl must point to a publicly accessible image. Ensure the URL does not require authentication or session cookies to access.

​
Step 2: Submit the Image Generation Request

Send the request to the AI Studio image generation endpoint. The process is identical to text-to-image generation, with the addition of the referenceImageUrl field. 
async function generateImageFromReference() {
  try {
    console.log("Submitting reference-based image generation request...");

    const response = await axios.post(
      `${API_BASE_URL}/v1/aistudio/images`,
      imageRequest,
      {
        headers: {
          "Content-Type": "application/json",
          Authorization: API_KEY,
        },
      }
    );

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

    return jobId;
  } catch (error) {
    console.error("Error submitting request:", error.response?.data || error.message);
    throw error;
  }
}

​
Step 3: Poll for the Result

Check the job status at regular intervals until the image is ready. 
async function waitForImage(jobId) {
  console.log("\nPolling for image generation result...");

  while (true) {
    const response = await axios.get(
      `${API_BASE_URL}/v1/jobs/${jobId}`,
      {
        headers: { Authorization: API_KEY },
      }
    );

    const data = response.data;
    const status = data.data.status;
    console.log("Status:", status);

    if (status === "completed") {
      console.log("\nImage generated successfully!");
      console.log("Image URL:", data.data.url);
      console.log("Dimensions:", data.data.width, "x", data.data.height);
      console.log("AI Credits Used:", data.data.aiCreditsUsed);
      return data;
    }

    if (status === "failed") {
      throw new Error("Image generation failed: " + JSON.stringify(data));
    }

    // Wait 15 seconds before polling again
    await new Promise(resolve => setTimeout(resolve, 15000));
  }
}

// Run the complete workflow
generateImageFromReference()
  .then(jobId => waitForImage(jobId))
  .then(result => console.log("\nDone!"))
  .catch(error => console.error("Error:", error));

​
Understanding the Parameters

ParameterTypeRequiredDefaultDescription
promptstringYes—A text description that explains what to generate, referencing or modifying the source image. Must be between 5 and 5,000 characters.
modelstringNoseedream3.0The AI model to use for generation. Supported values: seedream3.0, flux-schnell, nanobanana, nanobanana-pro. See Generate Image API for model capabilities and pricing.
aspectRatiostringNoFirst supported ratio of the selected modelThe output aspect ratio. Valid values depend on the selected model (e.g., 1:1, 16:9, 9:16).
stylestringNo—Visual style to apply to the generated image. Supported values: photorealistic, artistic, cartoon, minimalist, vintage, futuristic.
referenceImageUrlstringNo—A publicly accessible URL of the image to use as a visual reference. Must be a valid URI.
webhookstringNo—A URL to receive a POST notification when the job completes. Must be a valid URI.

​
Tips for Reference-Based Generation

  • Describe the change clearly. State what should be modified from the reference image. For example, “Replace the car with a bicycle” is more effective than “Change the vehicle.”
  • Mention the reference explicitly. Use phrases such as “in the referenced image” or “based on the provided image” so the model understands the relationship between the prompt and the reference.
  • Preserve scene context. If you want to keep the background or composition, say so in the prompt. For example, “Keep the background and lighting unchanged.”
  • Combine with styles. Applying a style such as "artistic" or "cartoon" transforms the reference into a different visual treatment while preserving the subject and layout.

​
Next Steps