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

# Generate Image

> Generate an AI image from a text prompt using a selection of AI image models

## 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 a reference image to guide the output. The API returns a job ID that you can use to poll for the result once the image generation is complete.

<Note>
  A valid API key is required to use this endpoint. Obtain your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## API Endpoint

```http theme={null}
POST https://api.pictory.ai/pictoryapis/v1/aistudio/images
```

***

## Request Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

***

## Request Body

<ParamField body="prompt" type="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"`
</ParamField>

<ParamField body="model" type="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`, `nanobanana-pro`

  **Model Capabilities and Pricing:**

  | Model            | Supported Aspect Ratios | AI Credits per Image |
  | ---------------- | ----------------------- | -------------------- |
  | `seedream3.0`    | `1:1`, `16:9`, `9:16`   | 2                    |
  | `flux-schnell`   | `1:1`, `16:9`, `9:16`   | 0.6                  |
  | `nanobanana`     | `1:1`, `16:9`, `9:16`   | 4                    |
  | `nanobanana-pro` | `1:1`, `16:9`, `9:16`   | 14                   |
</ParamField>

<ParamField body="aspectRatio" type="string">
  The aspect ratio for the generated image. The available values depend on the selected model. Defaults to the first supported aspect ratio of the chosen model. Refer to the model table above for supported aspect ratios per model.
</ParamField>

<ParamField body="style" type="string">
  An optional visual style to apply to the generated image.

  **Supported values:** `photorealistic`, `artistic`, `cartoon`, `minimalist`, `vintage`, `futuristic`
</ParamField>

<ParamField body="referenceImageUrl" type="string">
  An optional URL of a reference image to guide the generation. The URL must be a valid, publicly accessible URI.
</ParamField>

<ParamField body="webhook" type="string">
  An optional webhook URL that will receive a notification when the image generation job completes. The URL must be a valid URI.
</ParamField>

***

## Response

### Success Response (200)

<ResponseField name="success" type="boolean">
  `true` when the job has been created successfully
</ResponseField>

<ResponseField name="data" type="object">
  <ResponseField name="jobId" type="string">
    The unique identifier (UUID) of the image generation job. Use this ID to poll for the result using the [Get Image Generation Job](/api-reference/ai-studio/get-image-job) endpoint.
  </ResponseField>
</ResponseField>

### Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  {
      "success": true,
      "data": {
          "jobId": "4d82d040-4394-4371-867d-72ae1dd62b6d"
      }
  }
  ```

  ```json 400 - Validation Error theme={null}
  {
      "code": "INVALID_REQUEST_BODY",
      "message": "Request body validation failed.",
      "fields": [
          {
              "field": "prompt",
              "message": "\"prompt\" is required"
          }
      ]
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
      "message": "Unauthorized"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
      "message": "Internal Server Error"
  }
  ```
</ResponseExample>

***

## Status Codes

| Status Code | Description                                                                    |
| ----------- | ------------------------------------------------------------------------------ |
| **200**     | Job created successfully. Use the returned `jobId` to poll for the result.     |
| **400**     | Invalid request body. Check the `fields` array for specific validation errors. |
| **401**     | Unauthorized. The API key in the `Authorization` header is missing or invalid. |
| **500**     | Internal server error. Retry the request after a brief delay.                  |

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key from the [API Access page](https://app.pictory.ai/api-access).
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.pictory.ai/pictoryapis/v1/aistudio/images' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "prompt": "A serene mountain landscape at sunset with a reflective lake in the foreground",
      "model": "seedream3.0",
      "aspectRatio": "16:9",
      "style": "photorealistic"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.pictory.ai/pictoryapis/v1/aistudio/images"
  headers = {
      "Authorization": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "prompt": "A serene mountain landscape at sunset with a reflective lake in the foreground",
      "model": "seedream3.0",
      "aspectRatio": "16:9",
      "style": "photorealistic"
  }

  response = requests.post(url, json=payload, headers=headers)
  data = response.json()

  if data.get("success"):
      job_id = data["data"]["jobId"]
      print(f"Image generation job created: {job_id}")
  else:
      print(f"Error: {data}")
  ```

  ```javascript JavaScript theme={null}
  const url = 'https://api.pictory.ai/pictoryapis/v1/aistudio/images';

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: 'A serene mountain landscape at sunset with a reflective lake in the foreground',
      model: 'seedream3.0',
      aspectRatio: '16:9',
      style: 'photorealistic'
    })
  });

  const data = await response.json();

  if (data.success) {
    console.log(`Image generation job created: ${data.data.jobId}`);
  } else {
    console.log('Error:', data);
  }
  ```

  ```php PHP theme={null}
  <?php
  $url = "https://api.pictory.ai/pictoryapis/v1/aistudio/images";
  $payload = json_encode([
      "prompt" => "A serene mountain landscape at sunset with a reflective lake in the foreground",
      "model" => "seedream3.0",
      "aspectRatio" => "16:9",
      "style" => "photorealistic"
  ]);

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: YOUR_API_KEY',
      'Content-Type: application/json'
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);

  if ($data['success']) {
      echo "Image generation job created: " . $data['data']['jobId'] . "\n";
  } else {
      echo "Error: " . json_encode($data) . "\n";
  }
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      url := "https://api.pictory.ai/pictoryapis/v1/aistudio/images"

      payload := map[string]string{
          "prompt":      "A serene mountain landscape at sunset with a reflective lake in the foreground",
          "model":       "seedream3.0",
          "aspectRatio": "16:9",
          "style":       "photorealistic",
      }
      jsonPayload, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
      req.Header.Set("Authorization", "YOUR_API_KEY")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          fmt.Println("Error:", err)
          return
      }
      defer resp.Body.Close()

      body, _ := io.ReadAll(resp.Body)
      var data map[string]interface{}
      json.Unmarshal(body, &data)

      if success, ok := data["success"].(bool); ok && success {
          jobData := data["data"].(map[string]interface{})
          fmt.Printf("Image generation job created: %s\n", jobData["jobId"])
      } else {
          fmt.Println("Error:", string(body))
      }
  }
  ```
</CodeGroup>

***

## Next Steps

After receiving the `jobId`, poll for the image generation result using the [Get Image Generation Job](/api-reference/ai-studio/get-image-job) endpoint. Use a polling interval of **10–30 seconds** to check the job status.