> For the complete documentation index, see [llms.txt](https://bountyv.gitbook.io/vdocs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bountyv.gitbook.io/vdocs/account/generations.md).

# Generations history

List, retrieve, or download your persisted image generations. Every successful image generation is stored automatically and assigned a `generation_id` — use these endpoints to recall results later without having to store the raw bytes yourself.

## Authentication

All endpoints on this page require a Bearer API key. See [Authentication](/vdocs/authentication.md).

***

## List generations

```
GET /api/v1/generations
```

Synchronous.

### Request

No body. Query parameters only.

| Field    | Type    | Required | Default | Description                                                                            |
| -------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------- |
| `limit`  | integer | —        | `30`    | Page size. Clamped to a maximum of `100`                                               |
| `cursor` | string  | —        | —       | `created_at` timestamp from the previous page's `next_cursor`. Omit for the first page |

Results are ordered newest first.

### Response

```json
{
  "items": [
    {
      "id": "gJ8nP3kQ2m",
      "kind": "text_to_image",
      "prompt": "A neon-lit alley in Kyoto at midnight",
      "identity_id": null,
      "width": 896,
      "height": 1200,
      "seed": 42,
      "charged_cents": 18,
      "elapsed_ms": 31420,
      "created_at": "2026-05-18T12:34:56.000Z",
      "url": "https://substance-api.com/api/v1/generations/gJ8nP3kQ2m/download"
    }
  ],
  "next_cursor": "2026-05-18T12:34:56.000Z"
}
```

| Field                              | Type            | Description                                                                                                          |
| ---------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `items[].id`                       | string          | Generation ID                                                                                                        |
| `items[].kind`                     | string          | Public pipeline label, e.g. `text_to_image`, `image_to_image`, `image_to_video`, `identity_create`, `identity_image` |
| `items[].prompt`                   | string \| null  | Prompt used, if any                                                                                                  |
| `items[].identity_id`              | string \| null  | Associated identity (VSoul) ID, if any                                                                               |
| `items[].width` / `items[].height` | integer \| null | Output dimensions in pixels                                                                                          |
| `items[].seed`                     | integer \| null | Seed used, if applicable                                                                                             |
| `items[].charged_cents`            | integer \| null | Amount charged for this generation                                                                                   |
| `items[].elapsed_ms`               | integer \| null | Generation time in milliseconds                                                                                      |
| `items[].created_at`               | ISO 8601        | When the generation was created                                                                                      |
| `items[].url`                      | string          | Authenticated download endpoint on our domain — send the same `Authorization` header to fetch the image bytes        |
| `next_cursor`                      | string \| null  | Pass back as `cursor` to fetch the next page; `null` when there are no more results                                  |

### Example

```bash
curl "https://substance-api.com/api/v1/generations?limit=50" \
  -H "Authorization: Bearer sk_live_..."
```

***

## Retrieve one generation

```
GET /api/v1/generations/{id}
```

Synchronous. Returns the same metadata shape as a single list item, including the authenticated download URL.

### Request

No body. `{id}` is the generation ID from the list endpoint or from a generation pipeline's own response.

### Response

```json
{
  "id": "gJ8nP3kQ2m",
  "kind": "text_to_image",
  "prompt": "A neon-lit alley in Kyoto at midnight",
  "identity_id": null,
  "width": 896,
  "height": 1200,
  "seed": 42,
  "charged_cents": 18,
  "elapsed_ms": 31420,
  "created_at": "2026-05-18T12:34:56.000Z",
  "url": "https://substance-api.com/api/v1/generations/gJ8nP3kQ2m/download"
}
```

Fields are identical to a single item in the list response above.

### Example

```bash
curl https://substance-api.com/api/v1/generations/gJ8nP3kQ2m \
  -H "Authorization: Bearer sk_live_..."
```

***

## Download the image bytes

```
GET /api/v1/generations/{id}/download
```

Synchronous. Streams the image bytes back through our own domain — the customer never sees the upstream storage URL. Use this instead of decoding the inline base64 image returned by generation endpoints, or to save the file to your own storage.

### Request

No body. Authenticate with the same Bearer key used elsewhere on the v1 surface; only the owning account can fetch a given generation.

### Response

Raw image bytes (`Content-Type: image/png` by default) with `Content-Disposition: inline; filename="{id}.png"`.

### Example

```bash
curl https://substance-api.com/api/v1/generations/gJ8nP3kQ2m/download \
  -H "Authorization: Bearer sk_live_..." \
  --output out.png
```

***

## Errors

| Status | When                                                       |
| ------ | ---------------------------------------------------------- |
| `401`  | Missing, malformed, or revoked API key                     |
| `403`  | Account disabled — contact support                         |
| `404`  | Generation doesn't exist or doesn't belong to your account |
| `429`  | Rate limit exceeded for your key                           |
| `500`  | Failed to load the list, or the stored file is unavailable |

See [Errors](/vdocs/errors.md) for the full error format.

## Pricing

Billed per call — see [Credits & pricing](/vdocs/account/credits.md) for current rates. Listing, retrieving, and downloading generations is free; you're only charged by the generation pipeline that created the record in the first place.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bountyv.gitbook.io/vdocs/account/generations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.