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

# Batch Operations

> Generate multiple images efficiently with batch processing

# Batch Operations

Generate multiple images from a single template with different variables. Ideal for bulk generation of social cards, certificates, or personalized content.

## Endpoints

| Method | Endpoint                             | Description                                              |
| ------ | ------------------------------------ | -------------------------------------------------------- |
| `POST` | `/templates/{uid}/batch-render`      | [Start batch job](/api-reference/endpoints/batch/render) |
| `GET`  | `/templates/batch/{batchId}/results` | [Get results](/api-reference/endpoints/batch/results)    |
| `POST` | `/templates/batch/{batchId}/cancel`  | [Cancel batch](/api-reference/endpoints/batch/cancel)    |

## Batch Status

| Status       | Description                      |
| ------------ | -------------------------------- |
| `pending`    | Job created, waiting to start    |
| `processing` | Currently rendering images       |
| `completed`  | All items processed successfully |
| `partial`    | Completed with some failures     |
| `failed`     | All items failed                 |
| `cancelled`  | Job was cancelled                |

## Webhook Notification

When a batch job completes, Pictify sends a `batch.completed` event to your webhook URL (if provided):

```json theme={null}
{
  "event": "batch.completed",
  "data": {
    "batchId": "batch_xyz789",
    "status": "completed",
    "totalCount": 100,
    "completedCount": 100,
    "failedCount": 0
  }
}
```

## Limits

| Plan       | Max Items per Batch | Concurrent Batches |
| ---------- | ------------------- | ------------------ |
| Free       | 10                  | 1                  |
| Pro        | 100                 | 3                  |
| Business   | 1,000               | 10                 |
| Enterprise | 10,000              | Unlimited          |

## Best Practices

1. **Use webhooks** -- don't poll for results; use webhooks for notification
2. **Handle failures gracefully** -- some items may fail; implement retry logic
3. **Batch appropriately** -- group related renders; avoid tiny batches
4. **Monitor progress** -- track batch status for long-running jobs
5. **Clean up** -- results are stored for 7 days; download and store permanently if needed


## OpenAPI

````yaml post /templates/{uid}/batch-render
openapi: 3.1.0
info:
  title: Pictify API
  version: 1.0.0
  description: |
    Generate images, GIFs, and PDFs from HTML templates programmatically.

    ## Authentication
    All API requests require a Bearer token in the Authorization header:
    ```
    Authorization: Bearer pk_live_your_api_key
    ```

    ## Rate Limits
    - Free: 60 requests/minute
    - Pro: 300 requests/minute
    - Business: 1,000 requests/minute

    Rate limit headers are included in all responses.
  contact:
    email: support@pictify.io
    url: https://pictify.io
  license:
    name: MIT
servers:
  - url: https://api.pictify.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Images
    description: Image generation endpoints
  - name: GIFs
    description: GIF generation and capture
  - name: PDFs
    description: PDF generation
  - name: Templates
    description: Template management
  - name: Batch
    description: Batch rendering operations
  - name: Experiments
    description: A/B testing, smart links, and scheduled variant experiments
  - name: Webhooks
    description: Webhook subscription management
  - name: Bindings
    description: Data binding for auto-rendering
paths:
  /templates/{uid}/batch-render:
    post:
      tags:
        - Batch
      summary: Batch render template
      description: Generate multiple images from a template in one request
      operationId: batchRenderTemplate
      parameters:
        - name: uid
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRenderRequest'
      responses:
        '202':
          description: Batch job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
components:
  schemas:
    BatchRenderRequest:
      type: object
      required:
        - variableSets
      properties:
        variableSets:
          type: array
          items:
            type: object
            additionalProperties: true
          minItems: 1
          maxItems: 100
        format:
          type: string
          enum:
            - png
            - jpeg
            - webp
          default: png
        quality:
          type: number
          minimum: 0.1
          maximum: 1
          default: 0.9
        layout:
          type: string
          pattern: ^[a-z0-9-]{1,64}$
          description: Layout variant to use for all batch items. Omit for default layout.
        layouts:
          type: array
          items:
            type: string
            pattern: ^[a-z0-9-]{1,64}$
          description: >-
            Array of layout variant names to render for all batch items. Use
            instead of `layout` to render multiple layouts per item.
        concurrency:
          type: integer
          minimum: 1
          maximum: 10
          default: 5
    BatchResponse:
      type: object
      properties:
        batchId:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
            - partial
            - cancelled
        totalItems:
          type: integer
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from the Pictify dashboard

````