---
title: "Create a template with the authoring agent"
method: POST
path: "/v1/agent/templates"
tags: ["Agent"]
---

# Create a template with the authoring agent

`POST /v1/agent/templates`

Describe the image template you want; the TemplateFox agent authors it for you —
valid HTML that renders deterministically AND stays editable in the visual editor,
with every layer named and drivable through `/v1/image/create` modifications.

The job is asynchronous: poll `GET /v1/agent/jobs/{job_id}`. When completed, the
response always includes a **preview_url** (rendered PNG) plus the `template_id`.
Iterate with `POST /v1/agent/templates/{template_id}/revise`.

**Authentication:** API Key required (`x-api-key` header)

## Credits

Creation costs **25 credits**, deducted when the job is
queued and fully refunded if the job fails.

## Canvas

Pass a `preset` (instagram-square, instagram-story, og-image, twitter-card, pinterest-pin, square-512) or explicit `width` + `height` in px.

## Rate Limits

Standard rate limits apply (60 req/min free, 120 req/min paid).

## Request body

- CreateAgentTemplateRequest
  - `instructions` string, required — What the template should look like and which layers it needs, in natural language.
  - `name` string, required — Template name
  - `preset` 'instagram-square' | 'instagram-story' | 'og-image' | 'twitter-card' | 'pinterest-pin' | 'square-512', nullable — Canvas preset (or pass width + height)
  - `width` integer, nullable — Canvas width in px
  - `height` integer, nullable — Canvas height in px
  - `brand` BrandInputs — Optional brand constraints passed to the agent.
    - `colors` string[] — Brand colors as hex strings, e.g. ['#0C3C5F', '#E27D28']
    - `fonts` string[] — Preferred font families. Non-built-in fonts are substituted with the closest built-in and noted in the result.
    - `asset_urls` string[] — Public https:// URLs of assets (logo, photos) the agent may use.

## Response `200`

Job queued

- AgentJobCreatedResponse
  - `job_id` string, required
  - `status` 'pending', required
  - `credits_charged` integer, required
  - `credits_remaining` integer, required

## Other responses

- `402` — Insufficient credits
- `403` — Template limit reached for the current plan
- `422` — Invalid payload (canvas, colors, URLs)
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/pdftemplateapi/apis/templatefox-api.md) · [All operations](https://skmtc.net/pdftemplateapi/apis/templatefox-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pdftemplateapi/templatefox-api/revisions/5673fc0d5fad/schema)