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

# Get Generated Images

> Retrieve a paginated list of all AI-generated images

## Overview

This endpoint retrieves a paginated list of all AI-generated images associated with your account. The results are sorted by creation date in descending order, with the most recent images returned first. Each item includes the image URL, prompt, model, dimensions, and other metadata from the original generation request.

<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}
GET https://api.pictory.ai/pictoryapis/v1/aistudio/images
```

***

## Request Parameters

### Headers

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

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

### Query Parameters

<ParamField query="nextPageKey" type="string">
  A pagination token returned in the previous response. Pass this value to retrieve the next page of results. Omit this parameter to fetch the first page.
</ParamField>

***

## Response

### Success Response (200)

<ResponseField name="items" type="array">
  An array of generated image objects, sorted by creation date (newest first). Up to 100 items are returned per page.

  <Expandable title="Image Object Properties">
    <ResponseField name="url" type="string">
      Direct download URL for the generated image file
    </ResponseField>

    <ResponseField name="id" type="string">
      The unique identifier of the generated image
    </ResponseField>

    <ResponseField name="prompt" type="string">
      The text prompt that was used to generate this image
    </ResponseField>

    <ResponseField name="aspectRatio" type="string">
      The aspect ratio of the generated image (e.g., `"16:9"`, `"9:16"`, `"1:1"`)
    </ResponseField>

    <ResponseField name="createdDate" type="string">
      ISO 8601 timestamp of when the image was generated
    </ResponseField>

    <ResponseField name="model" type="string">
      The AI model that was used for generation (e.g., `"seedream3.0"`, `"nanobanana"`)
    </ResponseField>

    <ResponseField name="width" type="number">
      Width of the generated image in pixels
    </ResponseField>

    <ResponseField name="height" type="number">
      Height of the generated image in pixels
    </ResponseField>

    <ResponseField name="style" type="string">
      The visual style that was applied, if specified in the original request (e.g., `"photorealistic"`, `"artistic"`)
    </ResponseField>

    <ResponseField name="referenceImageUrl" type="string">
      The reference image URL that was provided in the original request, if applicable
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="nextPageKey" type="string">
  A pagination token to retrieve the next page of results. This field is only present when additional pages are available. Pass this value as the `nextPageKey` query parameter in the next request.
</ResponseField>

### Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  {
      "items": [
          {
              "url": "https://example.cloudfront.net/images/user/a1b2c3d4-e5f6-7890-abcd-ef1234567890/c3d4e5f6-a7b8-9012-cdef-345678901234.png",
              "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
              "prompt": "A modern workspace with an open laptop on a clean desk, illuminated by warm daylight from a nearby window",
              "aspectRatio": "16:9",
              "createdDate": "2026-04-04T06:03:38.665Z",
              "model": "nanobanana",
              "width": 1024,
              "height": 1024,
              "style": "photorealistic",
              "referenceImageUrl": "https://example.cloudfront.net/images/user/a1b2c3d4-e5f6-7890-abcd-ef1234567890/b2c3d4e5-f6a7-8901-bcde-234567890123.png"
          },
          {
              "url": "https://example.cloudfront.net/images/user/a1b2c3d4-e5f6-7890-abcd-ef1234567890/e5f6a7b8-c9d0-1234-efab-567890123456.png",
              "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
              "prompt": "A man playing guitar on a beach during sunset",
              "aspectRatio": "16:9",
              "createdDate": "2026-03-15T21:26:36.239Z",
              "model": "seedream3.0",
              "width": 1280,
              "height": 720
          }
      ],
      "nextPageKey": "eyJwYXJ0aXRpb25LZXkiOiJ1c2VyI..."
  }
  ```

  ```json 200 - Empty Result theme={null}
  {
      "items": []
  }
  ```

  ```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**     | Request processed successfully. The `items` array contains the generated images. An empty array is returned if no images have been generated. |
| **401**     | Unauthorized. The API key in the `Authorization` header is missing or invalid.                                                                |
| **500**     | Internal server error. Retry the request after a brief delay.                                                                                 |

***

## Response Fields

| Field               | Type   | Description                                                              |
| ------------------- | ------ | ------------------------------------------------------------------------ |
| `url`               | string | Direct download URL for the generated image                              |
| `id`                | string | Unique identifier of the generated image                                 |
| `prompt`            | string | The text prompt used to generate the image                               |
| `aspectRatio`       | string | Aspect ratio of the image (e.g., `"16:9"`)                               |
| `createdDate`       | string | ISO 8601 creation timestamp                                              |
| `model`             | string | AI model used for generation                                             |
| `width`             | number | Image width in pixels                                                    |
| `height`            | number | Image height in pixels                                                   |
| `style`             | string | Visual style applied (present only if specified in the original request) |
| `referenceImageUrl` | string | Reference image URL (present only if specified in the original request)  |

***

## Pagination

The API returns up to 100 images per page. If more results are available, the response includes a `nextPageKey` field. To retrieve subsequent pages, pass this token as a query parameter in the next request.

**Example paginated request:**

```
GET https://api.pictory.ai/pictoryapis/v1/aistudio/images?nextPageKey=eyJwYXJ0aXRpb25LZXkiOiJ1c2VyI...
```

When no `nextPageKey` is present in the response, you have reached the last page.

***

## 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 GET \
    --url 'https://api.pictory.ai/pictoryapis/v1/aistudio/images' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'accept: application/json' | python -m json.tool
  ```

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

  def get_all_images(api_key):
      """
      Retrieve all generated images with automatic pagination.
      """
      url = "https://api.pictory.ai/pictoryapis/v1/aistudio/images"
      headers = {
          "Authorization": api_key,
          "accept": "application/json"
      }

      all_images = []
      next_page_key = None

      while True:
          params = {}
          if next_page_key:
              params["nextPageKey"] = next_page_key

          response = requests.get(url, headers=headers, params=params)
          response.raise_for_status()

          data = response.json()
          items = data.get("items", [])
          all_images.extend(items)

          print(f"Fetched {len(items)} images (total: {len(all_images)})")

          next_page_key = data.get("nextPageKey")
          if not next_page_key:
              break

      return all_images

  # Usage
  images = get_all_images("YOUR_API_KEY")
  for image in images:
      print(f"{image['createdDate']} - {image['model']} - {image['url']}")
  ```

  ```javascript JavaScript theme={null}
  async function getAllImages(apiKey) {
    const url = 'https://api.pictory.ai/pictoryapis/v1/aistudio/images';
    const allImages = [];
    let nextPageKey = null;

    while (true) {
      const params = new URLSearchParams();
      if (nextPageKey) {
        params.set('nextPageKey', nextPageKey);
      }

      const requestUrl = params.toString()
        ? `${url}?${params.toString()}`
        : url;

      const response = await fetch(requestUrl, {
        method: 'GET',
        headers: {
          'Authorization': apiKey,
          'accept': 'application/json'
        }
      });

      const data = await response.json();
      const items = data.items || [];
      allImages.push(...items);

      console.log(`Fetched ${items.length} images (total: ${allImages.length})`);

      nextPageKey = data.nextPageKey;
      if (!nextPageKey) break;
    }

    return allImages;
  }

  // Usage
  const images = await getAllImages('YOUR_API_KEY');
  images.forEach(img => {
    console.log(`${img.createdDate} - ${img.model} - ${img.url}`);
  });
  ```

  ```php PHP theme={null}
  <?php
  function getAllImages($apiKey) {
      $url = "https://api.pictory.ai/pictoryapis/v1/aistudio/images";
      $allImages = [];
      $nextPageKey = null;

      while (true) {
          $requestUrl = $url;
          if ($nextPageKey) {
              $requestUrl .= "?nextPageKey=" . urlencode($nextPageKey);
          }

          $ch = curl_init($requestUrl);
          curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
          curl_setopt($ch, CURLOPT_HTTPHEADER, [
              'Authorization: ' . $apiKey,
              'accept: application/json'
          ]);

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

          $data = json_decode($response, true);
          $items = $data['items'] ?? [];
          $allImages = array_merge($allImages, $items);

          echo "Fetched " . count($items) . " images (total: " . count($allImages) . ")\n";

          $nextPageKey = $data['nextPageKey'] ?? null;
          if (!$nextPageKey) break;
      }

      return $allImages;
  }

  // Usage
  $images = getAllImages('YOUR_API_KEY');
  foreach ($images as $image) {
      echo "{$image['createdDate']} - {$image['model']} - {$image['url']}\n";
  }
  ?>
  ```

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

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

  func getAllImages(apiKey string) ([]map[string]interface{}, error) {
      baseURL := "https://api.pictory.ai/pictoryapis/v1/aistudio/images"
      var allImages []map[string]interface{}
      nextPageKey := ""

      for {
          requestURL := baseURL
          if nextPageKey != "" {
              requestURL = fmt.Sprintf("%s?nextPageKey=%s", baseURL, url.QueryEscape(nextPageKey))
          }

          req, _ := http.NewRequest("GET", requestURL, nil)
          req.Header.Set("Authorization", apiKey)
          req.Header.Set("accept", "application/json")

          client := &http.Client{}
          resp, err := client.Do(req)
          if err != nil {
              return nil, err
          }

          body, _ := io.ReadAll(resp.Body)
          resp.Body.Close()

          var data map[string]interface{}
          json.Unmarshal(body, &data)

          items, _ := data["items"].([]interface{})
          for _, item := range items {
              if img, ok := item.(map[string]interface{}); ok {
                  allImages = append(allImages, img)
              }
          }

          fmt.Printf("Fetched %d images (total: %d)\n", len(items), len(allImages))

          if key, ok := data["nextPageKey"].(string); ok && key != "" {
              nextPageKey = key
          } else {
              break
          }
      }

      return allImages, nil
  }

  func main() {
      images, err := getAllImages("YOUR_API_KEY")
      if err != nil {
          fmt.Println("Error:", err)
          return
      }

      for _, img := range images {
          fmt.Printf("%s - %s - %s\n", img["createdDate"], img["model"], img["url"])
      }
  }
  ```
</CodeGroup>