API

Images

POST /v1/images — generate AI images from a text prompt.

#POST /v1/images

Generate one or more AI images from a text prompt. This endpoint is synchronous: it returns the hosted image URLs directly (no job to poll). Generated images are stored in your workspace image library, so you can reuse them in any deck image field.

Base URL: https://heydecks.com

Requires Pro plan or higher. Costs 8 credits per image. Credits are refunded automatically for any image that fails to generate.

#Request body

Name	Type	Required	Description
`prompt`	string	Yes	What to depict. Keep it visual and specific. Maximum 2 000 characters.
`aspect_ratio`	string	No	One of `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `21:9`. Default `16:9`.
`n`	number	No	How many images to generate, 1 to 6. Default `1`. Each image costs 8 credits.

#Request example

curl

Shell

curl -X POST https://heydecks.com/v1/images \
  -H "Authorization: Bearer hd_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A calm abstract gradient backdrop in deep blue, soft studio light, no text",
    "aspect_ratio": "16:9",
    "n": 2
  }'

python

Python

import httpx

resp = httpx.post(
    "https://heydecks.com/v1/images",
    headers={"Authorization": "Bearer hd_live_…"},
    json={
        "prompt": "A calm abstract gradient backdrop in deep blue, soft studio light, no text",
        "aspect_ratio": "16:9",
        "n": 2,
    },
)
images = resp.json()["images"]  # [{"url": "https://…"}, {"url": "https://…"}]

#200 Response

Name	Type	Description
`images`	array	One object per generated image.
`images[].url`	string	Public URL of the hosted image. Use it in any image field or as a brand image.

JSON

{
  "images": [
    { "url": "https://pub-….r2.dev/ws/…/ai/abc123.png" },
    { "url": "https://pub-….r2.dev/ws/…/ai/def456.png" }
  ]
}

#Errors

Code	HTTP	When
`api_not_on_plan`	403	Your plan does not include API access. Pro plan required.
`invalid_input`	422	Missing or invalid `prompt`, `aspect_ratio`, or `n`.
`insufficient_credits`	402	Not enough credits. Each image costs 8 credits.
`generation_failed`	502	The image service was unavailable. No credits are charged for failed images.
`rate_limit`	429	Too many requests. Retry after 1 second.

#Notes

Generation typically takes a few seconds per image. Requesting more images increases the response time.
Generated images are permanent and live in your workspace image library. List them with the dashboard image picker, or reuse the returned URLs directly.
The same capability is available in the dashboard AI creator and as the MCP generate_image tool.