Generate photos

POST/generate

Makes new photos from one product photo. Without a model: product photos in the setting your prompt describes. With a model: the product worn by a Garmo model (or your own), in planned poses, in a catalog scene or one Garmo picks.

Cost: 1 credit per image. Images: Send exactly one photo: image_url, image_base64 or upload_id (or a multipart file named image). It makes count images (1 to 4). Category, scene and gender are only accepted together with model.

Overview and examples: Photoshoot API.

Parameters

ParameterDescription
promptstringWhat you want, in your own words and any language (up to 500 characters): setting, light, props, mood. Without a model it decides everything, including whether hands or a person appear; with a model it is the art direction. Leave it out and Garmo plans the set.
countintegerHow many images, 1 to 4. Each is a different angle or pose. Default 1.
modelstringPut the product on a model: an id from GET /catalog/models (a Garmo model or custom_<id> for your own), or "auto" to let Garmo pick one. Leave it out for product photos without a model.
categorystringWith a model: what the product is, so the poses fit. Default "clothing".One of: clothing, shoes, jewelry
scenestringWith a model: the place. auto plans a setting that suits the product. Default "auto".One of: auto, studio, street, editorial
genderstringWith model "auto": who wears it. Default "female".One of: female, male
aspect_ratiostringShape of the images. Default "3:4".One of: 3:4, 2:3, 1:1, 4:5, 9:16
image_urlstringPublic https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused.
image_base64stringThe photo itself, base64-encoded (a data: URI is fine). For large files use upload_id instead.
upload_idstringAn id from POST /uploads.
webhook_urlstringhttps address Garmo POSTs the finished job to (signed, see Webhooks).
metadataobjectYour own JSON object (up to 1,000 characters), returned with the job and in the webhook.

Header Idempotency-Key (optional): see Retries and idempotency.

Example

curl https://api.garmo.studio/v1/generate \
  -H "Authorization: Bearer $GARMO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://shop.example/products/sundress-41.jpg",
    "model": "auto",
    "prompt": "a sunlit stone colonnade, warm late-afternoon light",
    "count": 2
  }'

Response: 202 Accepted

202 Accepted
{
  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
  "object": "job",
  "tool": "generate",
  "status": "processing",
  "livemode": true,
  "outputs": [
    {
      "id": "out_1",
      "status": "processing",
      "label": "Front"
    },
    {
      "id": "out_2",
      "status": "processing",
      "label": "Walking"
    }
  ],
  "credits_charged": 2,
  "credits_refunded": 0,
  "metadata": {
    "sku": "DR-123"
  },
  "created_at": "2026-11-19T14:02:11Z",
  "completed_at": null
}

The finished job

GET /jobs/{id}
{
  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
  "object": "job",
  "tool": "generate",
  "status": "completed",
  "livemode": true,
  "outputs": [
    {
      "id": "out_1",
      "status": "succeeded",
      "label": "Front",
      "url": "https://….r2.cloudflarestorage.com/renders/2026/11/8f3c…0.webp?X-Amz-Signature=…",
      "url_expires_at": "2026-11-20T14:00:00Z"
    },
    {
      "id": "out_2",
      "status": "succeeded",
      "label": "Walking",
      "url": "https://….r2.cloudflarestorage.com/renders/2026/11/8f3c…1.webp?X-Amz-Signature=…",
      "url_expires_at": "2026-11-20T14:00:00Z"
    }
  ],
  "credits_charged": 2,
  "credits_refunded": 0,
  "metadata": {
    "sku": "DR-123"
  },
  "created_at": "2026-11-19T14:02:11Z",
  "completed_at": "2026-11-19T14:02:58Z"
}

Errors

400 invalid_request names the parameter that is missing or wrong. Image problems are invalid_image, image_too_large or image_unreachable. 402 insufficient_credits says how many credits the request needs. All codes: Errors.