Generate Mockup

curl --request POST \
  --url https://api.example.com/api/v1/generate \
  --header 'Content-Type: application/json' \
  --data '
{
  "designUrl": "<string>",
  "garmentId": "<string>",
  "garmentImageUrl": "<string>",
  "color": "<string>",
  "zone": "<string>",
  "placement": {
    "placement.x": 123,
    "placement.y": 123,
    "placement.scale": 123,
    "placement.rotation": 123
  },
  "applyTexture": true,
  "webhookUrl": "<string>"
}
'

{
  "id": "<string>",
  "status": "<string>",
  "mockupUrl": "<string>",
  "thumbnailUrl": "<string>",
  "tokensUsed": 123,
  "createdAt": "<string>",
  "completedAt": "<string>",
  "error": "<string>"
}

POST

api

generate

Generate Mockup

curl --request POST \
  --url https://api.example.com/api/v1/generate \
  --header 'Content-Type: application/json' \
  --data '
{
  "designUrl": "<string>",
  "garmentId": "<string>",
  "garmentImageUrl": "<string>",
  "color": "<string>",
  "zone": "<string>",
  "placement": {
    "placement.x": 123,
    "placement.y": 123,
    "placement.scale": 123,
    "placement.rotation": 123
  },
  "applyTexture": true,
  "webhookUrl": "<string>"
}
'

{
  "id": "<string>",
  "status": "<string>",
  "mockupUrl": "<string>",
  "thumbnailUrl": "<string>",
  "tokensUsed": 123,
  "createdAt": "<string>",
  "completedAt": "<string>",
  "error": "<string>"
}

Generate Mockup

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

Each generation costs 1 token.

Endpoint

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

Request Body

designUrl

string

required

URL of the design image to place on the garment. Must be publicly accessible.

garmentId

string

required

ID of the garment from the /garments endpoint.

garmentImageUrl

string

required

Direct URL to the garment blank image (specific color variant).

color

string

Color variant name (e.g., “Black”, “White”, “Navy”).

zone

string

default:"front"

Print zone to use. Options: front, back, left-chest, right-chest.

placement

object

Design placement configuration.

Show Placement properties

placement.x

number

default:"50"

Horizontal position (0-100%). 50 = centered.

placement.y

number

default:"35"

Vertical position (0-100%). 35 = typical chest placement.

placement.scale

number

default:"0.8"

Size scale (0.1-1.0). 1.0 = maximum print area.

placement.rotation

number

default:"0"

Rotation in degrees (-180 to 180).

applyTexture

boolean

default:"true"

Apply subtle fabric texture effect for realism.

webhookUrl

string

URL to receive a POST callback when generation completes.

Response

string

Unique generation ID (e.g., gen_1703001234_abc123).

status

string

Generation status: pending, processing, completed, or failed.

mockupUrl

string

URL of the generated mockup image (when completed).

thumbnailUrl

string

URL of a smaller thumbnail version.

tokensUsed

number

Number of tokens consumed (always 1).

createdAt

string

ISO 8601 timestamp of when the generation started.

completedAt

string

ISO 8601 timestamp of when the generation finished.

error

string

Error message if status is failed.

Example

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
    }
  }'

Response Example

{
  "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:

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

Webhook requests have a 10-second timeout. Respond with a 200 status quickly.

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

Errors List Garments

​Generate Mockup

​Endpoint

​Request Body

​Response

​Example

​Response Example

​Webhooks

​Errors

Generate Mockup

Endpoint

Request Body

Response

Example

Response Example

Webhooks

Errors