> 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/youtube-tools-api/thumbnail-prompt.md).

# Prompt assistant

Turn a rough concept (and an optional reference image) into an optimized thumbnail prompt.

```
POST /api/v1/thumbnail/prompt
```

Synchronous. A conversational helper that rewrites your idea into a production-ready text-to-image prompt tuned for high-converting thumbnails. It is **not billed** — any key with the `image` product can call it. Feed the returned text straight into `customPrompt` on [Create Thumbnails](/vdocs/youtube-tools-api/thumbnail-generate.md).

## Authentication

Like [Create Thumbnails](/vdocs/youtube-tools-api/thumbnail-generate.md), this endpoint reads your key from `apiKey` in the request body (form field or JSON), not the `Authorization` header. See [Authentication](/vdocs/authentication.md) for general details.

## Request

Accepts either `application/json` or `multipart/form-data`. Use form-data when you want to attach a reference image.

| Field     | Type   | Required | Description                                                                          |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------ |
| `apiKey`  | string | ✅        | Your Substance API key (`sk_live_...`).                                              |
| `message` | string | ✅        | Your concept or the change you want, e.g. "make it look like a horror movie poster". |
| `history` | array  | —        | Optional prior turns for multi-turn refinement: \`\[{ "role": "user"                 |
| `image`   | file   | —        | Optional reference image to analyze and fold into the prompt (multipart only).       |

## Response

```json
{
  "reply": "Hyper-detailed reaction thumbnail, central subject with a shocked expression, cinematic lighting, bold high-contrast composition, vivid electric-blue background, dramatic rim light…"
}
```

| Field   | Type   | Description                                                                             |
| ------- | ------ | --------------------------------------------------------------------------------------- |
| `reply` | string | The generated prompt text. Pass it into `customPrompt` on `/api/v1/thumbnail/generate`. |

## Example

```bash
curl -X POST https://substance-api.com/api/v1/thumbnail/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "'$SUBSTANCE_API_KEY'",
    "message": "A reaction thumbnail about a shocking phone leak"
  }'
```

## Errors

| Status | When                                                   |
| ------ | ------------------------------------------------------ |
| `400`  | Missing `apiKey` or `message`, or an unparseable body. |
| `401`  | Missing/invalid/revoked API key.                       |
| `403`  | Account does not have the `image` product enabled.     |
| `502`  | The assistant returned no text — safe to retry.        |

See [Errors](/vdocs/errors.md) for full details.

## Pricing

Free — this endpoint is not billed. See [Credits & pricing](/vdocs/account/credits.md) for rates on the endpoints that are.


---

# 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/youtube-tools-api/thumbnail-prompt.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.