---
name: garmo
description: Make and edit fashion and product photos with the Garmo API - new product or on-model photos from one product photo and a prompt, recolor clothes, change pose or model, ghost mannequin, change or remove the background, upscale to 4K. Use when the user wants photos made or edited with Garmo, or product photos for a shop, catalog or listing.
---

# Garmo API

Garmo makes and edits product photos for clothing, shoes, bags and jewelry. Base URL `https://api.garmo.studio/v1`.
Full docs: https://garmo.studio/api/docs/ (every page also as `.md`), all in one file: https://garmo.studio/api/docs/llms-full.txt

## Setup

- The key is in the environment as `GARMO_API_KEY` (`gm_test_…` or `gm_live_…`). Never print it or write it to a file. If it is missing, ask the user to create one in Garmo Studio › Developers › API.
- A test key costs nothing and returns the input photo as the "result": use it to check the flow first.
- Send `Authorization: Bearer $GARMO_API_KEY` on every request.

## Workflow

1. **Photo in.** A public https URL goes in `image_url`. A local file: `POST /uploads` as multipart (`file=@photo.jpg`) and pass the returned `id` as `upload_id`. JPEG, PNG or WebP, up to 12 MB.
2. **Create the job.** POST to the endpoint with JSON. Add an `Idempotency-Key` header (any unique string) so a retry never makes a second job. The answer is `202` with a job: `id` (`job_…`) and `status: "processing"`.
3. **Wait.** `GET /jobs/{id}` every 5 seconds until `status` is not `processing` (usually 20 to 90 seconds). On `429`, wait `Retry-After` seconds and try again.
4. **Save.** For each item in `outputs` with `status: "succeeded"`, download `url` (a signed link, valid about 24 hours) and save it, for example as `<photo-name>-<label>.webp`. Failed outputs have `error.code`; their credits are refunded.

Tell the user how many images were made, where they were saved and how many credits were charged (`credits_charged`, `credits_refunded`).

## Endpoints

- **POST /generate** (Generate photos, 1 credit per image): 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.
  - `prompt` (string): 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` (integer): How many images, 1 to 4. Each is a different angle or pose. Default 1.
  - `model` (string): 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` (string): With a model: what the product is, so the poses fit. One of: clothing, shoes, jewelry. Default "clothing".
  - `scene` (string): With a model: the place. auto plans a setting that suits the product. One of: auto, studio, street, editorial. Default "auto".
  - `gender` (string): With model "auto": who wears it. One of: female, male. Default "female".
  - `aspect_ratio` (string): Shape of the images. One of: 3:4, 2:3, 1:1, 4:5, 9:16. Default "3:4".
- **POST /edit/remove-background** (Remove background, 1 credit per photo): Cuts the product or model out of the photo, onto transparency, white or a color of your choice.
  - `background` (string): What the cut-out sits on. One of: transparent, white, color. Default "transparent".
  - `color_hex` (string): The color when background is "color", like "#efe8dc".
  - `shadow` (boolean): Adds a soft contact shadow under the subject (white and color backgrounds). Default false.
- **POST /edit/background** (Change background, 1 credit per scene): 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.
  - `scenes` (array): Scene ids from GET /catalog/scenes.
  - `description` (string): Your own scene in words (up to 300 characters).
  - `scene_image_url` (string): A photo of the place to use as the new background (or scene_image_base64, scene_image_upload_id).
  - `format` (string): Shape of the result; the scene is extended so nothing of the subject is cut off. One of: same, square, portrait, story. Default "same".
- **POST /edit/color** (Change clothing color, 1 credit): Recolors one garment to an exact hex color and keeps its fabric, folds, print and everything else in the photo.
  - `color_hex` (string, required): The new color, like "#c8553d".
  - `color_name` (string): A name for the color (up to 40 characters); helps with shades a hex alone leaves open.
  - `garment` (string): Which garment to recolor when there are several, like "dress" or "jacket".
- **POST /edit/pose** (Change pose, 1 credit per pose): Makes new photos of the same model in the same outfit and place, in other poses: back view, side, walking, seated and more.
  - `poses` (array): Pose ids from GET /catalog/poses. One of: standing, three, side, back, walking, seated, pockets, leaning.
  - `framing` (string): How much of the model is in frame. One of: full, knee, waist. Default "full".
  - `description` (string): A pose of your own in words (up to 200 characters).
  - `pose_image_url` (string): 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` (array): Up to 2 photos of the real back of the garment, so a back view is true to it.
- **POST /edit/model-swap** (Swap the model, 1 credit per model): Replaces the person in an on-model photo with another model, keeping the outfit, pose, framing and light.
  - `models` (array, required): Model ids from GET /catalog/models: Garmo models by name ("klara") or your own models in Garmo Studio ("custom_<id>").
- **POST /edit/ghost-mannequin** (Ghost mannequin, 1 credit): Turns a garment photo (on a model, mannequin or hanger) into an invisible-mannequin product shot with its worn 3D shape.
  - `background` (string): The background in a few words (up to 200 characters); a clean light studio background when empty.
- **POST /edit/upscale** (Upscale, 1 credit per photo at 2k, 2 at 4k): Makes a product photo sharp at 2048 or 4096 px on the long side, restoring fabric and material detail without changing the photo.
  - `resolution` (string): Long side of the result: 2k = 2048 px, 4k = 4096 px. One of: 2k, 4k. Default "2k".
  - `detail` (string): "enhanced" restores fine material detail; "natural" only sharpens what is there. One of: enhanced, natural. Default "enhanced".

All create endpoints also take `webhook_url` (https; Garmo POSTs the finished job there) and `metadata` (a JSON object returned with the job).
Ids for `models`, `scenes` and `poses`: `GET /catalog/models`, `GET /catalog/scenes`, `GET /catalog/poses`. Balance and limits: `GET /account`.

## Example

```bash
UPL=$(curl -s https://api.garmo.studio/v1/uploads -H "Authorization: Bearer $GARMO_API_KEY" -F file=@dress.jpg | jq -r .id)
JOB=$(curl -s https://api.garmo.studio/v1/generate -H "Authorization: Bearer $GARMO_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d "{\"upload_id\":\"$UPL\",\"model\":\"auto\",\"count\":2}" | jq -r .id)
until [ "$(curl -s https://api.garmo.studio/v1/jobs/$JOB -H "Authorization: Bearer $GARMO_API_KEY" | jq -r .status)" != processing ]; do sleep 5; done
curl -s https://api.garmo.studio/v1/jobs/$JOB -H "Authorization: Bearer $GARMO_API_KEY" | jq -r '.outputs[] | select(.status == "succeeded") | .url' \
  | { mkdir -p photos; n=0; while read -r url; do n=$((n + 1)); curl -s -o "photos/dress-$n.webp" "$url"; done; }
```

## Errors

Errors are `{"error": {"code", "message", "request_id"}}`. `invalid_request` names the parameter; `insufficient_credits` (402) means the API balance is too low (an API pack in Garmo Studio); `invalid_api_key` (401) means the key is wrong or revoked. Do not retry 4xx errors other than 429 without changing the request.
