{
  "openapi": "3.1.0",
  "info": {
    "title": "Garmo API",
    "version": "1.0.0",
    "summary": "AI photos and edits for fashion and product photos.",
    "description": "Garmo Studio over HTTP: generate product and on-model photos, and seven edits. Jobs are asynchronous: a create request answers 202 with a job; poll GET /jobs/{id} or receive a signed webhook. Docs: https://garmo.studio/api/docs/",
    "contact": {
      "email": "support@garmo.studio",
      "url": "https://garmo.studio/api/docs/"
    },
    "termsOfService": "https://garmo.studio/terms.html"
  },
  "servers": [
    {
      "url": "https://api.garmo.studio/v1"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "tags": [
    {
      "name": "Generate"
    },
    {
      "name": "Edits"
    },
    {
      "name": "Jobs"
    },
    {
      "name": "Account"
    },
    {
      "name": "Catalog"
    },
    {
      "name": "Uploads"
    }
  ],
  "paths": {
    "/generate": {
      "post": {
        "operationId": "generate",
        "summary": "Generate photos",
        "description": "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.\n\nSend exactly one photo: image_url, image_base64 or upload_id (or a multipart file named image). category, scene and gender are only accepted together with model.\n\nCost: 1 credit per image. Makes count images (1 to 4).",
        "tags": [
          "Generate"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "maxLength": 500,
                    "examples": [
                      "a sunlit stone colonnade, warm late-afternoon light"
                    ],
                    "description": "What 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."
                  },
                  "count": {
                    "type": "integer",
                    "default": 1,
                    "examples": [
                      2
                    ],
                    "description": "How many images, 1 to 4. Each is a different angle or pose."
                  },
                  "model": {
                    "type": "string",
                    "examples": [
                      "auto"
                    ],
                    "description": "Put 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."
                  },
                  "category": {
                    "type": "string",
                    "enum": [
                      "clothing",
                      "shoes",
                      "jewelry"
                    ],
                    "default": "clothing",
                    "description": "With a model: what the product is, so the poses fit."
                  },
                  "scene": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "studio",
                      "street",
                      "editorial"
                    ],
                    "default": "auto",
                    "description": "With a model: the place. auto plans a setting that suits the product."
                  },
                  "gender": {
                    "type": "string",
                    "enum": [
                      "female",
                      "male"
                    ],
                    "default": "female",
                    "description": "With model \"auto\": who wears it."
                  },
                  "aspect_ratio": {
                    "type": "string",
                    "enum": [
                      "3:4",
                      "2:3",
                      "1:1",
                      "4:5",
                      "9:16"
                    ],
                    "default": "3:4",
                    "description": "Shape of the images."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "The photo itself, base64-encoded (a data: URI is fine). For large files use upload_id instead."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  }
                }
              },
              "example": {
                "image_url": "https://shop.example/products/sundress-41.jpg",
                "model": "auto",
                "prompt": "a sunlit stone colonnade, warm late-afternoon light",
                "count": 2
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "maxLength": 500,
                    "examples": [
                      "a sunlit stone colonnade, warm late-afternoon light"
                    ],
                    "description": "What 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."
                  },
                  "count": {
                    "type": "integer",
                    "default": 1,
                    "examples": [
                      2
                    ],
                    "description": "How many images, 1 to 4. Each is a different angle or pose."
                  },
                  "model": {
                    "type": "string",
                    "examples": [
                      "auto"
                    ],
                    "description": "Put 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."
                  },
                  "category": {
                    "type": "string",
                    "enum": [
                      "clothing",
                      "shoes",
                      "jewelry"
                    ],
                    "default": "clothing",
                    "description": "With a model: what the product is, so the poses fit."
                  },
                  "scene": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "studio",
                      "street",
                      "editorial"
                    ],
                    "default": "auto",
                    "description": "With a model: the place. auto plans a setting that suits the product."
                  },
                  "gender": {
                    "type": "string",
                    "enum": [
                      "female",
                      "male"
                    ],
                    "default": "female",
                    "description": "With model \"auto\": who wears it."
                  },
                  "aspect_ratio": {
                    "type": "string",
                    "enum": [
                      "3:4",
                      "2:3",
                      "1:1",
                      "4:5",
                      "9:16"
                    ],
                    "default": "3:4",
                    "description": "Shape of the images."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  },
                  "image": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job was created and is processing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "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
                }
              }
            }
          },
          "200": {
            "description": "The same Idempotency-Key and body came before: the first job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request, invalid_image, image_too_large or image_unreachable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "api_not_enabled, account_suspended or key_suspended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "idempotency_conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited, concurrency_limited or overloaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/edit/remove-background": {
      "post": {
        "operationId": "edit_remove_background",
        "summary": "Remove background",
        "description": "Cuts the product or model out of the photo, onto transparency, white or a color of your choice.\n\nSend one photo the same way, or up to 10 in images[] (or multipart files named images[]).\n\nCost: 1 credit per photo. Makes one image per photo, at most 12 per request.",
        "tags": [
          "Edits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "background": {
                    "type": "string",
                    "enum": [
                      "transparent",
                      "white",
                      "color"
                    ],
                    "default": "transparent",
                    "description": "What the cut-out sits on."
                  },
                  "color_hex": {
                    "type": "string",
                    "examples": [
                      "#efe8dc"
                    ],
                    "description": "The color when background is \"color\", like \"#efe8dc\"."
                  },
                  "shadow": {
                    "type": "boolean",
                    "default": false,
                    "description": "Adds a soft contact shadow under the subject (white and color backgrounds)."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "The photo itself, base64-encoded (a data: URI is fine). For large files use upload_id instead."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "images": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ImageInput"
                    },
                    "description": "Several photos at once (up to 10); each item is a URL string or an object with image_url, image_base64 or upload_id. Each photo is edited on its own."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  }
                }
              },
              "example": {
                "image_url": "https://shop.example/products/bag-77.jpg",
                "background": "white",
                "shadow": true
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "background": {
                    "type": "string",
                    "enum": [
                      "transparent",
                      "white",
                      "color"
                    ],
                    "default": "transparent",
                    "description": "What the cut-out sits on."
                  },
                  "color_hex": {
                    "type": "string",
                    "examples": [
                      "#efe8dc"
                    ],
                    "description": "The color when background is \"color\", like \"#efe8dc\"."
                  },
                  "shadow": {
                    "type": "boolean",
                    "default": false,
                    "description": "Adds a soft contact shadow under the subject (white and color backgrounds)."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  },
                  "images[]": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job was created and is processing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
                  "object": "job",
                  "tool": "remove-background",
                  "status": "processing",
                  "livemode": true,
                  "outputs": [
                    {
                      "id": "out_1",
                      "status": "processing",
                      "label": "White · shadow"
                    }
                  ],
                  "credits_charged": 1,
                  "credits_refunded": 0,
                  "metadata": {
                    "sku": "DR-123"
                  },
                  "created_at": "2026-11-19T14:02:11Z",
                  "completed_at": null
                }
              }
            }
          },
          "200": {
            "description": "The same Idempotency-Key and body came before: the first job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request, invalid_image, image_too_large or image_unreachable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "api_not_enabled, account_suspended or key_suspended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "idempotency_conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited, concurrency_limited or overloaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/edit/background": {
      "post": {
        "operationId": "edit_background",
        "summary": "Change background",
        "description": "Keeps the subject exactly and puts it in a new place: a studio color, an interior, a street or a surface, with the light matched.\n\nSend exactly one photo: image_url, image_base64 or upload_id (or a multipart file named image). Give at least one of scenes, description or scene_image_url.\n\nCost: 1 credit per scene. Makes one image per scene (plus one for a description or scene photo), at most 12 per request.",
        "tags": [
          "Edits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scenes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "white",
                        "beige",
                        "grey",
                        "sage",
                        "lobby",
                        "cafe",
                        "gallery",
                        "living",
                        "paris",
                        "terrace",
                        "coast",
                        "desert",
                        "lake",
                        "marble",
                        "linen",
                        "wood",
                        "stone"
                      ]
                    },
                    "examples": [
                      [
                        "white",
                        "cafe"
                      ]
                    ],
                    "description": "Scene ids from GET /catalog/scenes."
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 300,
                    "examples": [
                      "a sunlit concrete loft with large windows"
                    ],
                    "description": "Your own scene in words (up to 300 characters)."
                  },
                  "scene_image_url": {
                    "type": "string",
                    "description": "A photo of the place to use as the new background (or scene_image_base64, scene_image_upload_id)."
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "same",
                      "square",
                      "portrait",
                      "story"
                    ],
                    "default": "same",
                    "description": "Shape of the result; the scene is extended so nothing of the subject is cut off."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "The photo itself, base64-encoded (a data: URI is fine). For large files use upload_id instead."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  }
                }
              },
              "example": {
                "image_url": "https://shop.example/products/linen-set-12.jpg",
                "scenes": [
                  "coast"
                ],
                "description": "a whitewashed Greek island lane with a blue door",
                "format": "same"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "scenes": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "white",
                        "beige",
                        "grey",
                        "sage",
                        "lobby",
                        "cafe",
                        "gallery",
                        "living",
                        "paris",
                        "terrace",
                        "coast",
                        "desert",
                        "lake",
                        "marble",
                        "linen",
                        "wood",
                        "stone"
                      ]
                    },
                    "examples": [
                      [
                        "white",
                        "cafe"
                      ]
                    ],
                    "description": "Scene ids from GET /catalog/scenes."
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 300,
                    "examples": [
                      "a sunlit concrete loft with large windows"
                    ],
                    "description": "Your own scene in words (up to 300 characters)."
                  },
                  "scene_image_url": {
                    "type": "string",
                    "description": "A photo of the place to use as the new background (or scene_image_base64, scene_image_upload_id)."
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "same",
                      "square",
                      "portrait",
                      "story"
                    ],
                    "default": "same",
                    "description": "Shape of the result; the scene is extended so nothing of the subject is cut off."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  },
                  "image": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job was created and is processing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
                  "object": "job",
                  "tool": "background",
                  "status": "processing",
                  "livemode": true,
                  "outputs": [
                    {
                      "id": "out_1",
                      "status": "processing",
                      "label": "Your scene"
                    },
                    {
                      "id": "out_2",
                      "status": "processing",
                      "label": "Coast at sunset"
                    }
                  ],
                  "credits_charged": 2,
                  "credits_refunded": 0,
                  "metadata": {
                    "sku": "DR-123"
                  },
                  "created_at": "2026-11-19T14:02:11Z",
                  "completed_at": null
                }
              }
            }
          },
          "200": {
            "description": "The same Idempotency-Key and body came before: the first job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request, invalid_image, image_too_large or image_unreachable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "api_not_enabled, account_suspended or key_suspended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "idempotency_conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited, concurrency_limited or overloaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/edit/color": {
      "post": {
        "operationId": "edit_color",
        "summary": "Change clothing color",
        "description": "Recolors one garment to an exact hex color and keeps its fabric, folds, print and everything else in the photo.\n\nSend exactly one photo: image_url, image_base64 or upload_id (or a multipart file named image).\n\nCost: 1 credit. Makes one image, at most 12 per request.",
        "tags": [
          "Edits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "color_hex": {
                    "type": "string",
                    "examples": [
                      "#c8553d"
                    ],
                    "description": "The new color, like \"#c8553d\"."
                  },
                  "color_name": {
                    "type": "string",
                    "examples": [
                      "terracotta"
                    ],
                    "description": "A name for the color (up to 40 characters); helps with shades a hex alone leaves open."
                  },
                  "garment": {
                    "type": "string",
                    "examples": [
                      "dress"
                    ],
                    "description": "Which garment to recolor when there are several, like \"dress\" or \"jacket\"."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "The photo itself, base64-encoded (a data: URI is fine). For large files use upload_id instead."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  }
                },
                "required": [
                  "color_hex"
                ]
              },
              "example": {
                "image_url": "https://shop.example/products/dress-123.jpg",
                "color_hex": "#c8553d",
                "color_name": "terracotta",
                "garment": "dress"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "color_hex": {
                    "type": "string",
                    "examples": [
                      "#c8553d"
                    ],
                    "description": "The new color, like \"#c8553d\"."
                  },
                  "color_name": {
                    "type": "string",
                    "examples": [
                      "terracotta"
                    ],
                    "description": "A name for the color (up to 40 characters); helps with shades a hex alone leaves open."
                  },
                  "garment": {
                    "type": "string",
                    "examples": [
                      "dress"
                    ],
                    "description": "Which garment to recolor when there are several, like \"dress\" or \"jacket\"."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  },
                  "image": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job was created and is processing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
                  "object": "job",
                  "tool": "color",
                  "status": "processing",
                  "livemode": true,
                  "outputs": [
                    {
                      "id": "out_1",
                      "status": "processing",
                      "label": "dress · terracotta"
                    }
                  ],
                  "credits_charged": 1,
                  "credits_refunded": 0,
                  "metadata": {
                    "sku": "DR-123"
                  },
                  "created_at": "2026-11-19T14:02:11Z",
                  "completed_at": null
                }
              }
            }
          },
          "200": {
            "description": "The same Idempotency-Key and body came before: the first job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request, invalid_image, image_too_large or image_unreachable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "api_not_enabled, account_suspended or key_suspended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "idempotency_conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited, concurrency_limited or overloaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/edit/pose": {
      "post": {
        "operationId": "edit_pose",
        "summary": "Change pose",
        "description": "Makes new photos of the same model in the same outfit and place, in other poses: back view, side, walking, seated and more.\n\nSend exactly one photo: image_url, image_base64 or upload_id (or a multipart file named image). Give at least one of poses, description or pose_image_url.\n\nCost: 1 credit per pose. Makes one image per pose (plus one for a description or pose photo), at most 12 per request.",
        "tags": [
          "Edits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "poses": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "standing",
                        "three",
                        "side",
                        "back",
                        "walking",
                        "seated",
                        "pockets",
                        "leaning"
                      ]
                    },
                    "examples": [
                      [
                        "back",
                        "walking"
                      ]
                    ],
                    "description": "Pose ids from GET /catalog/poses."
                  },
                  "framing": {
                    "type": "string",
                    "enum": [
                      "full",
                      "knee",
                      "waist"
                    ],
                    "default": "full",
                    "description": "How much of the model is in frame."
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "A pose of your own in words (up to 200 characters)."
                  },
                  "pose_image_url": {
                    "type": "string",
                    "description": "A photo of someone in the pose you want; only the pose is copied (or pose_image_base64, pose_image_upload_id)."
                  },
                  "back_image_urls": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 2 photos of the real back of the garment, so a back view is true to it."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "The photo itself, base64-encoded (a data: URI is fine). For large files use upload_id instead."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  }
                }
              },
              "example": {
                "image_url": "https://shop.example/products/jacket-7-on-model.jpg",
                "poses": [
                  "walking",
                  "side"
                ],
                "framing": "full"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "poses": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "standing",
                        "three",
                        "side",
                        "back",
                        "walking",
                        "seated",
                        "pockets",
                        "leaning"
                      ]
                    },
                    "examples": [
                      [
                        "back",
                        "walking"
                      ]
                    ],
                    "description": "Pose ids from GET /catalog/poses."
                  },
                  "framing": {
                    "type": "string",
                    "enum": [
                      "full",
                      "knee",
                      "waist"
                    ],
                    "default": "full",
                    "description": "How much of the model is in frame."
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "A pose of your own in words (up to 200 characters)."
                  },
                  "pose_image_url": {
                    "type": "string",
                    "description": "A photo of someone in the pose you want; only the pose is copied (or pose_image_base64, pose_image_upload_id)."
                  },
                  "back_image_urls": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Up to 2 photos of the real back of the garment, so a back view is true to it."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  },
                  "image": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job was created and is processing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
                  "object": "job",
                  "tool": "pose",
                  "status": "processing",
                  "livemode": true,
                  "outputs": [
                    {
                      "id": "out_1",
                      "status": "processing",
                      "label": "Walking"
                    },
                    {
                      "id": "out_2",
                      "status": "processing",
                      "label": "Side"
                    }
                  ],
                  "credits_charged": 2,
                  "credits_refunded": 0,
                  "metadata": {
                    "sku": "DR-123"
                  },
                  "created_at": "2026-11-19T14:02:11Z",
                  "completed_at": null
                }
              }
            }
          },
          "200": {
            "description": "The same Idempotency-Key and body came before: the first job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request, invalid_image, image_too_large or image_unreachable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "api_not_enabled, account_suspended or key_suspended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "idempotency_conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited, concurrency_limited or overloaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/edit/model-swap": {
      "post": {
        "operationId": "edit_model_swap",
        "summary": "Swap the model",
        "description": "Replaces the person in an on-model photo with another model, keeping the outfit, pose, framing and light.\n\nSend exactly one photo: image_url, image_base64 or upload_id (or a multipart file named image).\n\nCost: 1 credit per model. Makes one image per model, at most 12 per request.",
        "tags": [
          "Edits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "models": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "examples": [
                      [
                        "klara",
                        "kai"
                      ]
                    ],
                    "description": "Model ids from GET /catalog/models: Garmo models by name (\"klara\") or your own models in Garmo Studio (\"custom_<id>\")."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "The photo itself, base64-encoded (a data: URI is fine). For large files use upload_id instead."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  }
                },
                "required": [
                  "models"
                ]
              },
              "example": {
                "image_url": "https://shop.example/products/blazer-dress-9.jpg",
                "models": [
                  "amara",
                  "emma"
                ]
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "models": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "examples": [
                      [
                        "klara",
                        "kai"
                      ]
                    ],
                    "description": "Model ids from GET /catalog/models: Garmo models by name (\"klara\") or your own models in Garmo Studio (\"custom_<id>\")."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  },
                  "image": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job was created and is processing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
                  "object": "job",
                  "tool": "model-swap",
                  "status": "processing",
                  "livemode": true,
                  "outputs": [
                    {
                      "id": "out_1",
                      "status": "processing",
                      "label": "Amara"
                    },
                    {
                      "id": "out_2",
                      "status": "processing",
                      "label": "Emma"
                    }
                  ],
                  "credits_charged": 2,
                  "credits_refunded": 0,
                  "metadata": {
                    "sku": "DR-123"
                  },
                  "created_at": "2026-11-19T14:02:11Z",
                  "completed_at": null
                }
              }
            }
          },
          "200": {
            "description": "The same Idempotency-Key and body came before: the first job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request, invalid_image, image_too_large or image_unreachable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "api_not_enabled, account_suspended or key_suspended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "idempotency_conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited, concurrency_limited or overloaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/edit/ghost-mannequin": {
      "post": {
        "operationId": "edit_ghost_mannequin",
        "summary": "Ghost mannequin",
        "description": "Turns a garment photo (on a model, mannequin or hanger) into an invisible-mannequin product shot with its worn 3D shape.\n\nSend exactly one photo: image_url, image_base64 or upload_id (or a multipart file named image).\n\nCost: 1 credit. Makes one image, at most 12 per request.",
        "tags": [
          "Edits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "background": {
                    "type": "string",
                    "maxLength": 200,
                    "examples": [
                      "pure white"
                    ],
                    "description": "The background in a few words (up to 200 characters); a clean light studio background when empty."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "The photo itself, base64-encoded (a data: URI is fine). For large files use upload_id instead."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  }
                }
              },
              "example": {
                "image_url": "https://shop.example/products/oxford-shirt-4.jpg",
                "background": "light grey studio"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "background": {
                    "type": "string",
                    "maxLength": 200,
                    "examples": [
                      "pure white"
                    ],
                    "description": "The background in a few words (up to 200 characters); a clean light studio background when empty."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  },
                  "image": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job was created and is processing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
                  "object": "job",
                  "tool": "ghost-mannequin",
                  "status": "processing",
                  "livemode": true,
                  "outputs": [
                    {
                      "id": "out_1",
                      "status": "processing",
                      "label": "light grey studio"
                    }
                  ],
                  "credits_charged": 1,
                  "credits_refunded": 0,
                  "metadata": {
                    "sku": "DR-123"
                  },
                  "created_at": "2026-11-19T14:02:11Z",
                  "completed_at": null
                }
              }
            }
          },
          "200": {
            "description": "The same Idempotency-Key and body came before: the first job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request, invalid_image, image_too_large or image_unreachable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "api_not_enabled, account_suspended or key_suspended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "idempotency_conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited, concurrency_limited or overloaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/edit/upscale": {
      "post": {
        "operationId": "edit_upscale",
        "summary": "Upscale",
        "description": "Makes a product photo sharp at 2048 or 4096 px on the long side, restoring fabric and material detail without changing the photo.\n\nSend one photo the same way, or up to 10 in images[] (or multipart files named images[]).\n\nCost: 1 credit per photo at 2k, 2 at 4k. Makes one image per photo, at most 12 per request.",
        "tags": [
          "Edits"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "resolution": {
                    "type": "string",
                    "enum": [
                      "2k",
                      "4k"
                    ],
                    "default": "2k",
                    "description": "Long side of the result: 2k = 2048 px, 4k = 4096 px."
                  },
                  "detail": {
                    "type": "string",
                    "enum": [
                      "enhanced",
                      "natural"
                    ],
                    "default": "enhanced",
                    "description": "\"enhanced\" restores fine material detail; \"natural\" only sharpens what is there."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "image_base64": {
                    "type": "string",
                    "description": "The photo itself, base64-encoded (a data: URI is fine). For large files use upload_id instead."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "images": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/ImageInput"
                    },
                    "description": "Several photos at once (up to 10); each item is a URL string or an object with image_url, image_base64 or upload_id. Each photo is edited on its own."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  }
                }
              },
              "example": {
                "images": [
                  "https://shop.example/p/ring-1.jpg",
                  "https://shop.example/p/ring-2.jpg"
                ],
                "resolution": "4k"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "resolution": {
                    "type": "string",
                    "enum": [
                      "2k",
                      "4k"
                    ],
                    "default": "2k",
                    "description": "Long side of the result: 2k = 2048 px, 4k = 4096 px."
                  },
                  "detail": {
                    "type": "string",
                    "enum": [
                      "enhanced",
                      "natural"
                    ],
                    "default": "enhanced",
                    "description": "\"enhanced\" restores fine material detail; \"natural\" only sharpens what is there."
                  },
                  "image_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/products/dress-123.jpg"
                    ],
                    "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
                  },
                  "upload_id": {
                    "type": "string",
                    "examples": [
                      "upl_4821_9f2c1e0a7b3d5e6f"
                    ],
                    "description": "An id from POST /uploads."
                  },
                  "webhook_url": {
                    "type": "string",
                    "examples": [
                      "https://shop.example/hooks/garmo"
                    ],
                    "description": "https address Garmo POSTs the finished job to (signed, see Webhooks)."
                  },
                  "metadata": {
                    "type": "object",
                    "examples": [
                      {
                        "sku": "DR-123"
                      }
                    ],
                    "description": "Your own JSON object (up to 1,000 characters), returned with the job and in the webhook."
                  },
                  "images[]": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The job was created and is processing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
                  "object": "job",
                  "tool": "upscale",
                  "status": "processing",
                  "livemode": true,
                  "outputs": [
                    {
                      "id": "out_1",
                      "status": "processing",
                      "label": "4K"
                    },
                    {
                      "id": "out_2",
                      "status": "processing",
                      "label": "4K"
                    }
                  ],
                  "credits_charged": 4,
                  "credits_refunded": 0,
                  "metadata": {
                    "sku": "DR-123"
                  },
                  "created_at": "2026-11-19T14:02:11Z",
                  "completed_at": null
                }
              }
            }
          },
          "200": {
            "description": "The same Idempotency-Key and body came before: the first job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request, invalid_image, image_too_large or image_unreachable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "api_not_enabled, account_suspended or key_suspended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "idempotency_conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited, concurrency_limited or overloaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{id}": {
      "get": {
        "operationId": "get_job",
        "summary": "Get a job",
        "description": "The job and its outputs. Output links are signed and last 24 hours; each call returns current ones.",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "job_8Kq2xV7mPz4LtR9wNc3B"
          }
        ],
        "responses": {
          "200": {
            "description": "The job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
                  "object": "job",
                  "tool": "color",
                  "status": "completed",
                  "livemode": true,
                  "outputs": [
                    {
                      "id": "out_1",
                      "status": "succeeded",
                      "label": "dress · terracotta",
                      "url": "https://….r2.cloudflarestorage.com/renders/2026/11/8f3c…0.webp?X-Amz-Signature=…",
                      "url_expires_at": "2026-11-20T14:00:00Z"
                    }
                  ],
                  "credits_charged": 1,
                  "credits_refunded": 0,
                  "metadata": {
                    "sku": "DR-123"
                  },
                  "created_at": "2026-11-19T14:02:11Z",
                  "completed_at": "2026-11-19T14:02:58Z"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{id}/cancel": {
      "post": {
        "operationId": "cancel_job",
        "summary": "Cancel a job",
        "description": "Stops the outputs still rendering and refunds their credits. A finished job is returned unchanged.",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "job_8Kq2xV7mPz4LtR9wNc3B"
          }
        ],
        "responses": {
          "200": {
            "description": "The job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                },
                "example": {
                  "id": "job_8Kq2xV7mPz4LtR9wNc3B",
                  "object": "job",
                  "tool": "color",
                  "status": "completed",
                  "livemode": true,
                  "outputs": [
                    {
                      "id": "out_1",
                      "status": "succeeded",
                      "label": "dress · terracotta",
                      "url": "https://….r2.cloudflarestorage.com/renders/2026/11/8f3c…0.webp?X-Amz-Signature=…",
                      "url_expires_at": "2026-11-20T14:00:00Z"
                    }
                  ],
                  "credits_charged": 1,
                  "credits_refunded": 0,
                  "metadata": {
                    "sku": "DR-123"
                  },
                  "created_at": "2026-11-19T14:02:11Z",
                  "completed_at": "2026-11-19T14:02:58Z"
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/jobs": {
      "get": {
        "operationId": "list_jobs",
        "summary": "List jobs",
        "description": "Jobs of this account made with keys of the same mode (live or test), newest first.",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Between 1 and 100. Default 20."
          },
          {
            "name": "starting_after",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "A job id: list the jobs after it."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "processing, completed, failed or canceled."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of jobs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Job"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/account": {
      "get": {
        "operationId": "get_account",
        "summary": "Account",
        "description": "API credit balance, the calling key and its limits.",
        "tags": [
          "Account"
        ],
        "responses": {
          "200": {
            "description": "The account.",
            "content": {
              "application/json": {
                "example": {
                  "object": "account",
                  "livemode": true,
                  "api_credits": 482,
                  "key": {
                    "prefix": "gm_live_4e9P",
                    "name": "Shop sync",
                    "mode": "live"
                  },
                  "tier": "medium",
                  "limits": {
                    "create_requests_per_minute": 30,
                    "read_requests_per_minute": 300,
                    "concurrent_images": 10,
                    "images_per_request": 12
                  }
                }
              }
            }
          }
        }
      }
    },
    "/catalog/{kind}": {
      "get": {
        "operationId": "get_catalog",
        "summary": "Catalog",
        "description": "Ids for the edit parameters: kind is models, scenes or poses.",
        "tags": [
          "Catalog"
        ],
        "parameters": [
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "models",
                "scenes",
                "poses"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The list.",
            "content": {
              "application/json": {
                "example": {
                  "object": "list",
                  "has_more": false,
                  "data": [
                    {
                      "id": "back",
                      "name": "Back",
                      "description": "standing with their back to the camera …"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/uploads": {
      "post": {
        "operationId": "create_upload",
        "summary": "Upload a file",
        "description": "Sends a photo once and returns an upload_id to use in any edit (multipart field \"file\").",
        "tags": [
          "Uploads"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The upload.",
            "content": {
              "application/json": {
                "example": {
                  "id": "upl_4821_9f2c1e0a7b3d5e6f",
                  "object": "upload",
                  "size": 845211
                }
              }
            }
          },
          "400": {
            "description": "invalid_image or image_too_large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "An API key from Garmo Studio › Developers › API: gm_live_… or gm_test_…"
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "maxLength": 80
        },
        "description": "Send the same value to retry safely: within 24 hours the same key and body return the first job."
      }
    },
    "schemas": {
      "ImageInput": {
        "oneOf": [
          {
            "type": "string",
            "description": "A public https URL."
          },
          {
            "type": "object",
            "properties": {
              "image_url": {
                "type": "string",
                "examples": [
                  "https://shop.example/products/dress-123.jpg"
                ],
                "description": "Public https URL of the photo to edit. JPEG, PNG or WebP, up to 12 MB. Private and local addresses are refused."
              },
              "image_base64": {
                "type": "string",
                "description": "The photo itself, base64-encoded (a data: URI is fine). For large files use upload_id instead."
              },
              "upload_id": {
                "type": "string",
                "examples": [
                  "upl_4821_9f2c1e0a7b3d5e6f"
                ],
                "description": "An id from POST /uploads."
              }
            },
            "minProperties": 1,
            "maxProperties": 1
          }
        ]
      },
      "Output": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "processing",
              "succeeded",
              "failed"
            ]
          },
          "label": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Signed link to the image, valid about 24 hours."
          },
          "url_expires_at": {
            "type": "string"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "content_refused",
                  "generation_failed",
                  "timeout",
                  "canceled"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": {
            "description": "The job id, job_ plus 20 characters.",
            "type": "string"
          },
          "object": {
            "description": "Always \"job\".",
            "type": "string"
          },
          "tool": {
            "description": "The endpoint that made it: generate, remove-background, background, color, pose, model-swap, ghost-mannequin or upscale.",
            "type": "string"
          },
          "status": {
            "description": "\"processing\", then \"completed\" (at least one output succeeded), \"failed\" or \"canceled\".",
            "type": "string"
          },
          "livemode": {
            "description": "false for jobs made with a test key.",
            "type": "boolean"
          },
          "outputs": {
            "description": "One entry per image: id (out_1, out_2 …), status (\"processing\", \"succeeded\", \"failed\"), label, url and url_expires_at when succeeded, error {code, message} when failed.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Output"
            }
          },
          "credits_charged": {
            "description": "Credits taken when the job was created (0 for a test key).",
            "type": "integer"
          },
          "credits_refunded": {
            "description": "Credits given back for outputs that failed or were canceled.",
            "type": "integer"
          },
          "metadata": {
            "description": "Your metadata, or null.",
            "type": [
              "object",
              "null"
            ]
          },
          "created_at": {
            "description": "ISO 8601, UTC.",
            "type": "string"
          },
          "completed_at": {
            "description": "ISO 8601, UTC; null while processing.",
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "account_suspended",
                  "api_not_enabled",
                  "concurrency_limited",
                  "idempotency_conflict",
                  "idempotency_in_progress",
                  "image_too_large",
                  "image_unreachable",
                  "insufficient_credits",
                  "internal_error",
                  "invalid_api_key",
                  "invalid_image",
                  "invalid_request",
                  "key_suspended",
                  "not_found",
                  "overloaded",
                  "rate_limited",
                  "unavailable"
                ]
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {
    "job.finished": {
      "post": {
        "summary": "A job ended",
        "description": "Sent to the job's webhook_url when it ends: type job.completed, job.failed or job.canceled. Signed with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature) and your key's whsec_ secret.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "job.completed",
                      "job.failed",
                      "job.canceled"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/Job"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx ends the retries."
          }
        }
      }
    }
  }
}
