Skip to main content
This guide walks you through generating an AI image from a text prompt using the Pictory AI Studio API. You will learn how to submit a prompt, select a model and style, and retrieve the generated image by polling the job status.

​
What You Will Build

Text to Image

Generate images from descriptive text prompts

Model Selection

Choose from multiple AI image models

Style Control

Apply visual styles such as photorealistic, artistic, or cartoon

Job Polling

Monitor image generation and retrieve the result

​
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
npm install axios

​
Step-by-Step Guide

​
Step 1: Set Up Your Request

Prepare your API credentials and define the image prompt along with the desired model and style. 
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 configuration
const imageRequest = {
  prompt: "A golden retriever running through a sunlit meadow with wildflowers in the background",
  model: "seedream3.0",
  aspectRatio: "16:9",
  style: "photorealistic"
};

​
Step 2: Submit the Image Generation Request

Send the request to the AI Studio image generation endpoint. On success, the API returns a jobId that you will use to poll for the result. 
async function generateImage() {
  try {
    console.log("Submitting 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. The recommended polling interval is 10 to 30 seconds. 
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
generateImage()
  .then(jobId => waitForImage(jobId))
  .then(result => console.log("\nDone!"))
  .catch(error => console.error("Error:", error));

​
Understanding the Parameters

ParameterTypeRequiredDefaultDescription
promptstringYes—A descriptive text of the image to generate. 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 a reference image to guide the generation. Must be a valid URI.
webhookstringNo—A URL to receive a POST notification when the job completes. Must be a valid URI.

​
Tips for Effective Prompts

  • Be specific and descriptive. Include details about the subject, setting, lighting, and composition.
  • Specify the camera angle. Use terms such as “wide shot”, “close-up”, or “aerial view” to control framing.
  • Pair with a style. Combine your prompt with the style parameter for more consistent results. For example, use "photorealistic" for lifelike images or "artistic" for a painterly look.
  • Keep prompts focused. A single clear subject with a well-defined setting produces better results than a prompt that tries to describe too many elements at once.

​
Next Steps