> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a thumbnail generation

> Get status, dimensions and expiration for a thumbnail belonging to the connected account.

Get status, dimensions and expiration for a thumbnail belonging to the connected account.

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/thumbnails_get
```

## Authentication and permissions

<ParamField header="x-api-key" type="string" required>
  Send a VoiceCheap API key in this header. Authorization: Bearer with the same API key is also supported. OAuth access tokens are accepted only by
  MCP, not by this REST endpoint.
</ParamField>

Required permissions: `thumbnails:read`.

An active paid subscription is required. Permissions do not change team roles, resource ownership, media credits, or plan limits.

## Parameters

<ParamField body="generationId" type="string" required>
  Generation ID returned by a generation or history action.

  Pattern: `^[A-Za-z0-9_-]{1,128}$`.
</ParamField>

<Accordion title="Complete input schema">
  The JSON Schema below preserves the exact field names, nested types, defaults, bounds, and accepted values exposed by discovery. Additional cross-field rules are listed in the operation notes.

  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "generationId": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]{1,128}$",
        "description": "Generation ID returned by a generation or history action."
      }
    },
    "required": ["generationId"],
    "additionalProperties": false
  }
  ```
</Accordion>

## Request examples

Replace example resource identifiers and media keys with values returned for your account. Keep the request identifier stable when retrying the same mutation.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST 'https://api.voicecheap.ai/v1/actions/thumbnails_get' \
    --header "x-api-key: $VOICECHEAP_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{"generationId":"109c61cb35dbdc01a94aabb3b1a128519ed1f8823800a7a327b9d8d8c2c0e10b"}'
  ```

  ```javascript JavaScript theme={null}
  const input = {
    generationId: '109c61cb35dbdc01a94aabb3b1a128519ed1f8823800a7a327b9d8d8c2c0e10b',
  };
  const response = await fetch('https://api.voicecheap.ai/v1/actions/thumbnails_get', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.VOICECHEAP_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  });
  const body = await response.json();
  if (!response.ok) throw new Error(body.code + ': ' + body.message);
  console.log(body);
  ```

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

  response = requests.post(
      "https://api.voicecheap.ai/v1/actions/thumbnails_get",
      headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
      json={"generationId": "109c61cb35dbdc01a94aabb3b1a128519ed1f8823800a7a327b9d8d8c2c0e10b"},
      timeout=120,
  )
  body = response.json()
  if not response.ok:
      raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
  print(body)
  ```
</RequestExample>

## Response

A successful first execution returns HTTP 200 with the operation result under data. A replay may return saved request state instead. The example shows one supported response, not every optional field.

The connected user’s thumbnail metadata, including dimensions, reference count, status, and expiration. Claimed public-tool thumbnails can also be retrieved.

<ResponseExample>
  ```json HTTP 200 theme={null}
  {
    "data": {
      "generationId": "109c61cb35dbdc01a94aabb3b1a128519ed1f8823800a7a327b9d8d8c2c0e10b",
      "status": "completed",
      "width": 1280,
      "height": 720,
      "referenceImageCount": 1,
      "createdAt": 1792144800000,
      "updatedAt": 1792144800000,
      "expiresAt": 1792749600000
    }
  }
  ```
</ResponseExample>

## Result fields

| Field | Description |
| - | - |
| `data.generationId` | Identifier to pass unchanged to thumbnails\_get or thumbnails\_download. |
| `data.status` | completed, expired, or deleted. A deleted record remains deleted even after its expiry time. |
| `data.width` | Output width in pixels: 1280. |
| `data.height` | Output height in pixels: 720. |
| `data.referenceImageCount` | Number of reference images used: 0 to 3. |
| `data.createdAt` | Creation time in Unix milliseconds. |
| `data.updatedAt` | Last update time in Unix milliseconds. |
| `data.expiresAt` | Time in Unix milliseconds after which the generated thumbnail cannot be downloaded. |

## Operation notes

* Requires thumbnails:read. generationId must contain 1–128 ASCII letters, digits, underscores, or hyphens.
* This action uses the connected user’s own creations and uploads, including when the credential is connected in a team context.
* Metadata reports completed, expired, or deleted; no pending generation record is exposed by this action. For an active generation, poll action\_request\_get.
* The metadata record may still exist after expiration or deletion. Use thumbnails\_download for WebP bytes before expiresAt; a successful metadata read does not guarantee download availability.

## Usage

Each successful invocation consumes one monthly API/MCP call. Media credits and the operation's own generation allowances also apply.

## Errors

| HTTP status | Code | Meaning or recovery |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | Credentials were supplied in an access\_token or api\_key query parameter. Send credentials in headers. |
| 400 | `VALIDATION_ERROR` | An argument is missing, has an unsupported value, exceeds its limit, or is not part of the strict input schema. |
| 401 | `API_KEY_EXPIRED` | The API key has expired. |
| 401 | `INVALID_API_KEY` | Provide a valid, unexpired API key. |
| 401 | `INVALID_CREDENTIAL` | The Authorization header is malformed or conflicts with x-api-key. |
| 401 | `MISSING_CREDENTIAL` | No usable header credential was supplied, or it exceeded 4096 characters. |
| 401 | `USER_NOT_FOUND` | The credential's account no longer exists. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | The credential's user belongs to more than one team, so the billing context is ambiguous. |
| 403 | `INSUFFICIENT_SCOPE` | Grant every required permission or choose another credential. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | The account's integration limits could not be verified. |
| 403 | `SUBSCRIPTION_REQUIRED` | Use an active paid subscription. |
| 403 | `TEAM_OWNER_NOT_FOUND` | The effective team owner account could not be found. |
| 404 | `THUMBNAIL_NOT_FOUND` | The generation does not exist or is not claimed by the connected user. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Wait for the monthly reset or change plan. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Wait for Retry-After when present and use backoff. |
| 500 | `INTERNAL_ERROR` | Check saved request state and resource history before deciding to retry a mutation. |
| 503 | `SERVER_RESTARTING` | The server is restarting. Retry shortly and keep the same request identifier for a mutation. |

```json theme={null}
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This credential does not permit the requested action.",
  "status": 403,
  "details": {
    "requiredScopes": ["thumbnails:read"]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.