> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pixy.art/llms.txt
> Use this file to discover all available pages before exploring further.

# How to use

> Learn how to find IDs, build modifications, and send your first Pixy API request.

## What You Need

Before you send a generate request, you need:

1. An Automation key
2. A **design** `id`
3. One or more **element** `id` values for the parts you want to change

## Get An Automation Key

Create or copy an Automation key from your Pixy API settings.

[Get Automation key](https://app.pixy.art/automations)

## Install The SDK

If you prefer a wrapper instead of writing raw fetch requests, install the official npm package:

```bash theme={null}
npm install @pixy-art/sdk
```

## Search Public Templates

Use the public templates endpoint when you need a template `designId` to start from.

Supported query parameters:

* `search` filters templates by name or keyword
* `page` is a zero-based page index
* `perPage` controls how many templates are returned, up to 100
* `promoted` optionally filters promoted templates
* `orderBy` optionally controls ordering. Use `oldest` for oldest created templates first. Omit it for latest updated templates first.

<CodeGroup>
  ```ts SDK theme={null}
  import { Pixy } from '@pixy-art/sdk'

  const pixy = new Pixy({
    apiKey: 'YOUR_API_KEY',
  })

  const templates = await pixy.templates.list({
    search: 'plane',
    page: 0,
    perPage: 24,
    orderBy: 'oldest',
  })

  console.log(templates.data)
  ```

  ```bash cURL theme={null}
  curl -X GET "https://app.pixy.art/api/v1/templates?search=plane&page=0&perPage=24&orderBy=oldest" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

The response includes `data`, `total`, `page`, `perPage`, and `search`.
Each template includes its `id`, `name`, `thumbnail`, `category`, `size`, `orientation`, `fonts`, and supported export `formats`.
Use a returned template `id` as the `designId` for generation, or open it in the Embed editor with `openAsCopy: true`.

## Duplicate a Design

Use the duplicate endpoint when you need a separate editable copy of a design. The response returns a new `id`; saving or editing that copy will not change the source design.

If the source design was created through Embed with a `userId`, the copied design keeps the same association.

```bash cURL theme={null}
curl -X POST "https://app.pixy.art/api/v1/YOUR_DESIGN_ID/duplicate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Copy for campaign B"
  }'
```

## Find Design ID

Open the design or template in Pixy, then use the `Copy design id` action in the editor.

![Design ID placeholder](https://placehold.co/1200x675/f8f9fa/868e96?text=Find+design+id+placeholder)

## Find Element IDs

Once the design is open in the editor, select the element you want to modify and use `Copy element id`.

Typical targets include:

<AccordionGroup>
  <Accordion title="Text elements" icon="type">
    Use these when you want to change text content, fill color, or stroke color.

    ![Text element placeholder](https://placehold.co/1200x675/fff0f6/c2255c?text=Text+element+placeholder)
  </Accordion>

  <Accordion title="Image elements" icon="image">
    Use these when you want to swap the source image, or change stroke color.

    ![Image element placeholder](https://placehold.co/1200x675/f4fce3/2b8a3e?text=Image+element+placeholder)
  </Accordion>

  <Accordion title="SVG and shape elements" icon="pen-tool">
    Use these when you want to change fill or stroke color.

    ![Shape element placeholder](https://placehold.co/1200x675/eef2ff/4c6ef5?text=Shape+element+placeholder)
  </Accordion>
</AccordionGroup>

## Send Your First Request

Use your [authenticated](/authentication) Automation key to send `modifications` in the request body.

<CodeGroup>
  ```ts SDK theme={null}
  import { Pixy } from '@pixy-art/sdk'

  const pixy = new Pixy({
    apiKey: 'YOUR_API_KEY',
  })

  const image = await pixy.generate('YOUR_DESIGN_ID', [
    {
      id: 'TITLE_ID',
      text: 'Spring launch sale',
    },
  ])
  ```

  ```bash cURL theme={null}
  curl -X POST "https://app.pixy.art/api/v1/YOUR_DESIGN_ID/generate" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "modifications": [
        {
          "id": "YOUR_ELEMENT_ID",
          "text": "Spring launch sale"
        }
      ]
    }'
  ```
</CodeGroup>

If the request succeeds, the response includes the render `id`, the `designId`, total `duration`, and generated `files`, with each file returning its URL, size, dimensions, mimetype, and an optional `previewUrl` for outputs such as PDFs.

## Common Modification Patterns

<CodeGroup>
  ```ts SDK theme={null}
  const image = await pixy.generate('YOUR_DESIGN_ID', [
    { id: 'TITLE_ID', text: 'New season drop' },
    { id: 'IMAGE_ID', src: 'https://example.com/cover.jpg' },
    { id: 'ELEMENT_ID', fill: '#111827', stroke: '#ffffff' },
  ])
  ```

  ```bash cURL theme={null}
  curl -X POST "https://app.pixy.art/api/v1/YOUR_DESIGN_ID/generate" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "modifications": [
        { "id": "TITLE_ID", "text": "New season drop" },
        { "id": "IMAGE_ID", "src": "https://example.com/cover.jpg" },
        { "id": "ELEMENT_ID", "fill": "#111827", "stroke": "#ffffff" }
      ]
    }'
  ```
</CodeGroup>

## Supported Modifications

Review the full [Modifications](/modifications) guide for the supported fields, examples, and combinations.