--- title: "Generate an image from a template" method: POST path: "/designs/{uid}" tags: ["Images"] --- # Generate an image from a template `POST /designs/{uid}` ## Request - Base URL: `https://api.dynapictures.com` - URL: `https://api.dynapictures.com/designs/{uid}` - Auth: HTTP bearer Renders a template with your data and returns the image URLs. Works for single-page templates (`params`), multipage templates (`pages`) and PDFs (`format: pdf`). Each image or PDF page uses one image credit. Requests are not idempotent, so a repeated request uses another credit. ## Path parameters - `uid` string, required ## Request body - GenerateImageRequest: Every property is optional. An empty body renders the template as designed. - `format` 'png' | 'jpeg' | 'webp' | 'avif' | 'pdf' | 'pptx': Output format. `pdf` is for multipage templates and produces one file with every page. - `metadata` string: Custom data stored on the generated image and returned in responses and webhooks. - `params` LayerOverride[]: New values for the layers of a single-page template. - `name` string, required: The name of the layer to customize, shown in the settings panel when the layer is selected. `canvas` is the background. - `text` string: The text to render in a text layer. Basic HTML is supported and sanitized. - `color` string: The text color. E.g. `#000000`, `rgb(0,0,0)` or `rgba(0,0,0,0.5)`. - `fontSize` string: Font size of a text layer, e.g. `48px`. - `backgroundColor` string: The background color of the layer. E.g. `#000000`, `rgb(0,0,0)` or `rgba(0,0,0,0.5)`. - `borderColor` string: The border color of the layer. Set `borderWidth` as well. E.g. `#000000`, `rgb(0,0,0)` or `rgba(0,0,0,0.5)`. - `borderWidth` string: The border width of the layer, e.g. `1px`. - `borderRadius` string: The border radius of the layer, e.g. `5px` or `50%`. - `opacity` number: Layer opacity from `0` (hidden) to `1` (as designed). - `imageUrl` string, uri: The image to render in an image layer. - `imagePosition` 'cro' | 'cov' | 'ai_face' | 'align': How the image fits its container. Empty centers it. `cro` crops to fill, `cov` scales to cover, `ai_face` detects faces and keeps them visible, and `align` uses `imageAlignH` and `imageAlignV`. - `imageAlignH` 'left' | 'center' | 'right' | 'full': Horizontal image alignment when `imagePosition` is `align`. - `imageAlignV` 'top' | 'center' | 'bottom' | 'full': Vertical image alignment when `imagePosition` is `align`. - `imageEffect` string: A CSS filter applied to the image, e.g. `grayscale(100%)` or `blur(4px)`. - `prompt` string: Prompt for an AI Image layer in "Per request" mode. Supports `[name]` tokens that refer to `referenceImages`. - `sourceImage` string, uri: URL of a photo for an AI Image layer to edit. Omit it for text-to-image. - `referenceImages` ReferenceImage[]: Named reference images for an AI Image layer. - `name` string, required: Short name used in the prompt as `[name]`, e.g. `logo`. - `url` string, uri, required: Public URL of the reference image. - `chartColor` string: The color of the chart. E.g. `#000000`, `rgb(0,0,0)` or `rgba(0,0,0,0.5)`. - `chartLabelColor` string: The color of the chart axis labels. E.g. `#000000`, `rgb(0,0,0)` or `rgba(0,0,0,0.5)`. - `chartDataLabels` string[]: Labels shown on the X axis. - `chartDataValues` number[]: The data series of the chart. - `value` number: Progress value for gauge and line progress bar layers, usually `0` to `100`. - `maxValue` number: Total number of ticks of a radial tick gauge, e.g. `24`, `60` or `100`. - `activeColor` string: Color of the filled ticks of a radial tick gauge. - `inactiveColor` string: Color of the empty ticks of a radial tick gauge. - `circleColor` string: Color of the background ring of a simple gauge. - `progressColor` string: Color of the progress arc or of the filled part of a line progress bar. - `textColor` string: Color of the value label inside a simple gauge. - `remainingColor` string: Color of the unfilled track of a line progress bar. - `label` string: Overrides the label text of a line progress bar. - `labelAlign` 'left' | 'center' | 'right': Horizontal alignment of the line progress bar label. - `pages` PageOverride[]: New values for the pages of a multipage template, instead of `params`. - `index` integer, required: The page of the template this applies to, starting at 0. - `layers` LayerOverride[]: New values for the layers of this page. - `name` string, required: The name of the layer to customize, shown in the settings panel when the layer is selected. `canvas` is the background. - `text` string: The text to render in a text layer. Basic HTML is supported and sanitized. - `color` string: The text color. E.g. `#000000`, `rgb(0,0,0)` or `rgba(0,0,0,0.5)`. - `fontSize` string: Font size of a text layer, e.g. `48px`. - `backgroundColor` string: The background color of the layer. E.g. `#000000`, `rgb(0,0,0)` or `rgba(0,0,0,0.5)`. - `borderColor` string: The border color of the layer. Set `borderWidth` as well. E.g. `#000000`, `rgb(0,0,0)` or `rgba(0,0,0,0.5)`. - `borderWidth` string: The border width of the layer, e.g. `1px`. - `borderRadius` string: The border radius of the layer, e.g. `5px` or `50%`. - `opacity` number: Layer opacity from `0` (hidden) to `1` (as designed). - `imageUrl` string, uri: The image to render in an image layer. - `imagePosition` 'cro' | 'cov' | 'ai_face' | 'align': How the image fits its container. Empty centers it. `cro` crops to fill, `cov` scales to cover, `ai_face` detects faces and keeps them visible, and `align` uses `imageAlignH` and `imageAlignV`. - `imageAlignH` 'left' | 'center' | 'right' | 'full': Horizontal image alignment when `imagePosition` is `align`. - `imageAlignV` 'top' | 'center' | 'bottom' | 'full': Vertical image alignment when `imagePosition` is `align`. - `imageEffect` string: A CSS filter applied to the image, e.g. `grayscale(100%)` or `blur(4px)`. - `prompt` string: Prompt for an AI Image layer in "Per request" mode. Supports `[name]` tokens that refer to `referenceImages`. - `sourceImage` string, uri: URL of a photo for an AI Image layer to edit. Omit it for text-to-image. - `referenceImages` ReferenceImage[]: Named reference images for an AI Image layer. - `name` string, required: Short name used in the prompt as `[name]`, e.g. `logo`. - `url` string, uri, required: Public URL of the reference image. - `chartColor` string: The color of the chart. E.g. `#000000`, `rgb(0,0,0)` or `rgba(0,0,0,0.5)`. - `chartLabelColor` string: The color of the chart axis labels. E.g. `#000000`, `rgb(0,0,0)` or `rgba(0,0,0,0.5)`. - `chartDataLabels` string[]: Labels shown on the X axis. - `chartDataValues` number[]: The data series of the chart. - `value` number: Progress value for gauge and line progress bar layers, usually `0` to `100`. - `maxValue` number: Total number of ticks of a radial tick gauge, e.g. `24`, `60` or `100`. - `activeColor` string: Color of the filled ticks of a radial tick gauge. - `inactiveColor` string: Color of the empty ticks of a radial tick gauge. - `circleColor` string: Color of the background ring of a simple gauge. - `progressColor` string: Color of the progress arc or of the filled part of a line progress bar. - `textColor` string: Color of the value label inside a simple gauge. - `remainingColor` string: Color of the unfilled track of a line progress bar. - `label` string: Overrides the label text of a line progress bar. - `labelAlign` 'left' | 'center' | 'right': Horizontal alignment of the line progress bar label. - `responseFormat` 'json' | 'binary': `binary` returns the image bytes instead of JSON. Single-page image designs only. ## Response `200` The generated image. With `responseFormat: binary`, the image bytes. - union - GeneratedImage: A generated image, or a PDF when the format is `pdf`. - `id` string, required: The ID of the generated image. - `templateId` string: The ID of the template it was generated from. - `templateName` string: The name of that template. - `imageUrl` string, uri, required: URL of the generated image, or of the PDF when the format is `pdf`. - `thumbnailUrl` string, uri: Thumbnail URL, fitting a 300x300px square. - `retinaThumbnailUrl` string, uri: Thumbnail URL for retina displays, fitting a 600x600px square. - `metadata` string: The custom metadata sent with the request. - `width` integer: Image width in pixels. - `height` integer: Image height in pixels. - MultipageResult - `templateId` string, required: The ID of the template. - `templateName` string: The name of the template. - `pages` GeneratedPage[], required: One entry per generated page. - `id` string, required: The ID of the generated page image. - `imageUrl` string, uri, required: URL of the page image. - `thumbnailUrl` string, uri: Thumbnail URL of the page image. - `metadata` string: The custom metadata sent with the request. - `width` integer: Image width in pixels. - `height` integer: Image height in pixels. - `pageIndex` integer, required: The page of the template, starting at 0. ## Other responses - `400`: The request is invalid. `message` says why. - `401`: The API key is missing or wrong. - `403`: The plan limit is reached, the trial has expired, or the key has no access to this resource. - `404`: The resource does not exist, or the key has no access to it. - `500`: The render failed. With `error: "render_incomplete"`, a layer could not be rendered: the credit is used, and retrying renders again. - `504`: The render took longer than 120 seconds. The image may still have been generated, so check before retrying. --- [API](https://skmtc.dev/dynapictures/apis/dynapictures-api.md) - [All operations](https://skmtc.dev/dynapictures/apis/dynapictures-api/llms.txt) - [OpenAPI document](https://skmtc.dev/dynapictures/apis/dynapictures-api/revisions/a9820777cfb3?raw)