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

# Generate Mockup

> Create apparel mockups by compositing designs onto garments

# Generate Mockup

Composite a design image onto a garment blank to create a realistic mockup.

<Info>
  Each generation costs **1 token**.
</Info>

## Endpoint

```
POST https://garmint.app/api/v1/generate
```

## Request Body

<ParamField body="designUrl" type="string" required>
  URL of the design image to place on the garment. Must be publicly accessible.
</ParamField>

<ParamField body="garmentId" type="string" required>
  ID of the garment from the `/garments` endpoint.
</ParamField>

<ParamField body="garmentImageUrl" type="string" required>
  Direct URL to the garment blank image (specific color variant).
</ParamField>

<ParamField body="color" type="string">
  Color variant name (e.g., "Black", "White", "Navy").
</ParamField>

<ParamField body="zone" type="string" default="front">
  Print zone to use. Options: `front`, `back`, `left-chest`, `right-chest`.
</ParamField>

<ParamField body="placement" type="object">
  Design placement configuration.

  <Expandable title="Placement properties">
    <ParamField body="placement.x" type="number" default="50">
      Horizontal position (0-100%). 50 = centered.
    </ParamField>

    <ParamField body="placement.y" type="number" default="35">
      Vertical position (0-100%). 35 = typical chest placement.
    </ParamField>

    <ParamField body="placement.scale" type="number" default="0.8">
      Size scale (0.1-1.0). 1.0 = maximum print area.
    </ParamField>

    <ParamField body="placement.rotation" type="number" default="0">
      Rotation in degrees (-180 to 180).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="applyTexture" type="boolean" default="true">
  Apply subtle fabric texture effect for realism.
</ParamField>

<ParamField body="webhookUrl" type="string">
  URL to receive a POST callback when generation completes.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique generation ID (e.g., `gen_1703001234_abc123`).
</ResponseField>

<ResponseField name="status" type="string">
  Generation status: `pending`, `processing`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="mockupUrl" type="string">
  URL of the generated mockup image (when completed).
</ResponseField>

<ResponseField name="thumbnailUrl" type="string">
  URL of a smaller thumbnail version.
</ResponseField>

<ResponseField name="tokensUsed" type="number">
  Number of tokens consumed (always 1).
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the generation started.
</ResponseField>

<ResponseField name="completedAt" type="string">
  ISO 8601 timestamp of when the generation finished.
</ResponseField>

<ResponseField name="error" type="string">
  Error message if status is `failed`.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={}
  curl -X POST https://garmint.app/api/v1/generate \
    -H "Authorization: Bearer gm_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "designUrl": "https://example.com/my-design.png",
      "garmentId": "gildan-5000",
      "garmentImageUrl": "https://cdn.shopify.com/s/files/1/.../black-tee.png",
      "color": "Black",
      "placement": {
        "x": 50,
        "y": 35,
        "scale": 0.8
      }
    }'
  ```

  ```typescript TypeScript theme={}
  const response = await fetch('https://garmint.app/api/v1/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${GARMINT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      designUrl: 'https://example.com/my-design.png',
      garmentId: 'gildan-5000',
      garmentImageUrl: 'https://cdn.shopify.com/s/.../black-tee.png',
      color: 'Black',
      placement: { x: 50, y: 35, scale: 0.8 },
    }),
  });

  const mockup = await response.json();
  console.log(mockup.mockupUrl);
  ```

  ```python Python theme={}
  import requests

  response = requests.post(
      'https://garmint.app/api/v1/generate',
      headers={'Authorization': f'Bearer {GARMINT_API_KEY}'},
      json={
          'designUrl': 'https://example.com/my-design.png',
          'garmentId': 'gildan-5000',
          'garmentImageUrl': 'https://cdn.shopify.com/s/.../black-tee.png',
          'color': 'Black',
          'placement': {'x': 50, 'y': 35, 'scale': 0.8},
      }
  )

  mockup = response.json()
  print(mockup['mockupUrl'])
  ```
</CodeGroup>

## Response Example

```json theme={}
{
  "id": "gen_1703001234_abc123",
  "status": "completed",
  "mockupUrl": "https://res.cloudinary.com/garmint/image/upload/v123/api-generations/abc123.jpg",
  "thumbnailUrl": "https://res.cloudinary.com/garmint/image/upload/v123/api-generations/abc123.jpg",
  "tokensUsed": 1,
  "createdAt": "2024-12-19T12:00:00.000Z",
  "completedAt": "2024-12-19T12:00:02.500Z"
}
```

## Webhooks

If you provide a `webhookUrl`, we'll POST the completed generation to your endpoint:

```json theme={}
{
  "event": "generation.completed",
  "timestamp": "2024-12-19T12:00:02.500Z",
  "data": {
    "id": "gen_1703001234_abc123",
    "status": "completed",
    "mockupUrl": "https://...",
    "tokensUsed": 1
  }
}
```

<Warning>
  Webhook requests have a 10-second timeout. Respond with a `200` status quickly.
</Warning>

## Errors

| Code                  | Status | Description                             |
| --------------------- | ------ | --------------------------------------- |
| `invalid_request`     | 400    | Missing required fields or invalid URLs |
| `insufficient_tokens` | 402    | Not enough tokens                       |
| `not_found`           | 404    | Garment ID not found                    |