---
name: dynapictures-api
description: Generate personalized images, PDFs and AI images with DynaPictures. Use when a task needs banners, certificates, social images or product cards produced from a template and data, a multi-page PDF, or a standalone AI image.
---

# DynaPictures API

DynaPictures renders templates into images and PDFs. A template is designed once, and each request overrides its layers by name.

## Before you start

You need an API key from the user, sent as `Authorization: Bearer <key>`. A person has to copy it from <https://dynapictures.com/app/account>; see <https://dynapictures.com/auth.md>. Never put the key in a URL.

If the MCP server is available to you, prefer it: `https://mcp.dynapictures.com/mcp`. Otherwise call the REST API at `https://api.dynapictures.com`. The full description is at <https://dynapictures.com/openapi.json>.

## Generate an image from a template

1. Find the template. `GET /templates` returns templates with "Sync to Zapier" enabled, including their layer names. If the user gave you a UID, skip this step.
2. Call `POST /designs/{UID}`. Each entry in `params` targets one layer through `name`. Omit layers you don't want to change.

```json
{
  "format": "jpeg",
  "params": [
    { "name": "title", "text": "Summer sale" },
    { "name": "image1", "imageUrl": "https://example.com/photo.jpg", "imagePosition": "cov" }
  ]
}
```

3. Use `imageUrl` from the response. Set `"responseFormat": "binary"` to get the image bytes instead of JSON.

Multi-page templates take `pages` instead of `params`. Set `"format": "pdf"` to get one PDF.

## Generate a standalone AI image

1. `POST /ai/generate` with `modelId` and `prompt`, and optionally `ratio`, `sourceImage` and `referenceImages`. It returns `202` with a `jobUid`.
2. Poll `GET /ai/generate/{jobUid}` about every 2 seconds until `status` is `done` or `error`. Generation usually takes 10 to 60 seconds.
3. Use `resultUrl`, and download the image if it needs to be kept. The URL is not guaranteed to last.

## Embed an image by URL

`GET /links/{UID}.{format}?params=...` renders on request, so it works inside an `<img>` tag. Overrides use `{layer}---{property}___{value}`, joined with `<>`, and the whole `params` value must be URL-encoded. Identical URLs return a cached image and don't use another credit.

## Spending credits

Every generated image and PDF page uses one image credit. AI images use AI credits, which are sold separately. Requests are not idempotent, so a retried `POST /designs/{UID}` can use a second credit. If a request timed out, check whether the image exists before retrying.

## Errors

| Status | Meaning | What to do |
| ------ | ------- | ---------- |
| 400 | Invalid request | Read `message` and fix the request. |
| 401 | Missing or wrong API key | Ask the user for a valid key. |
| 402 | Out of AI credits | Tell the user to buy a credit pack. |
| 403 | Plan limit reached or trial expired | Tell the user. Don't retry. |
| 404 | Template or path not found | Check the UID. |
| 503 | Busy | Wait for the `Retry-After` value, then retry. |
| 504 | Render timed out | Check for the image before retrying. |