Skip to main content
POST
Generate Image

Overview

The Generate Image API creates an AI-generated image based on a text prompt. You can choose from multiple AI image models, specify an aspect ratio, apply a visual style, and optionally provide up to four reference images to edit or combine. The API returns a job ID that you can use to poll for the result once the image generation is complete.
A valid API key is required to use this endpoint. Obtain your API key from the API Access page in your Pictory dashboard.

API Endpoint


Request Headers

string
required
API key for authentication (starts with pictai_)
string
required
Must be application/json

Request Body

string
required
A text description of the image you want to generate. The prompt must be between 5 and 5,000 characters.Example: "A serene mountain landscape at sunset with a reflective lake in the foreground"
string
The AI model to use for image generation. Each model produces different visual styles and quality levels. Defaults to seedream3.0 if not specified.Supported models: seedream3.0, flux-schnell, nanobanana-lite2, nanobanana2, nanobanana, nanobanana-pro, nova-canvasModel Capabilities and Pricing:
nanobanana-lite2 cannot edit images itself. A request with reference images on nanobanana-lite2 is served by nanobanana2 and billed at the nanobanana-lite2 rate. Where “Aspect Ratio on Edits” says “Follows the reference”, the output keeps the reference image’s aspect ratio and the aspectRatio field only applies to generation without references.
string
The aspect ratio for the generated image. Every model accepts 1:1, 16:9, and 9:16. Defaults to 1:1. With reference images, the ratio is only honored on the models marked so in the table above; the others keep the reference image’s ratio.
string
The visual style to apply to the generated image. Defaults to photorealistic.Supported values: photorealistic, artistic, cartoon, minimalist, vintage, futuristic
array
An optional array of 1 to 4 reference image URLs. The model edits, combines, or restyles the referenced images according to the prompt. Each URL must be a valid, publicly accessible URI. Sending more references than the model allows returns a 400 validation error; sending references to flux-schnell returns a 400 with the code IMAGE_EDITING_NOT_SUPPORTED.
This parameter cannot be used together with referenceImageUrl.
string
A single reference image URL. Kept for existing integrations; it behaves exactly like a one-element referenceImageUrls. New integrations should use referenceImageUrls.
string
Steer the generation toward a training-content use case. The preset is a fixed directive applied during prompt enhancement, so sending it always turns enhancement on, even when enhancePrompt is false. Supported values: sales-training, product-training, soft-skills-training.
boolean
Whether Pictory rewrites your prompt with an AI enhancer before generation, adding cinematic and compositional detail. Off by default: your prompt goes to the model exactly as written. Set to true to enhance it. Sending a trainingPreset always turns enhancement on. Sending a style also turns it on, unless you set enhancePrompt: false. When enhancement runs, the completed job returns the rewritten text as enhancedPrompt.
string
An optional webhook URL that will receive a notification when the image generation job completes. The URL must be a valid URI.

Response

Success Response (200)

boolean
true when the job has been created successfully
object
string
The unique identifier (UUID) of the image generation job. Use this ID to poll for the result using the Get Image Generation Job endpoint.

Response Examples


Status Codes


Code Examples

Replace YOUR_API_KEY with your actual API key from the API Access page.

Next Steps

After receiving the jobId, poll for the image generation result using the Get Image Generation Job endpoint. Use a polling interval of 10–30 seconds to check the job status.