Vtry AI docs

Documentation

Learn the complete Vtry AI workflow in the interface, then use the API reference to build the same person, clothes, try-on, and edit flow from your backend.

Vtry AI API

Public API reference

Use the Vtry AI API from your backend to create people, upload clothes, queue virtual try-on jobs and poll the final image result. This page documents the exact request parameters for every public API endpoint.

Manage API Key Endpoint Reference

Access

Authentication

Create or rotate an API key from the account profile page. The full key is shown only once. Store it on your server and never expose it in client-side code.

Send the key with the Authorization header. The x-api-key header is also supported for server-side integrations that cannot set bearer tokens.

Authorization: Bearer YOUR_API_KEY

# Alternative header
x-api-key: YOUR_API_KEY

Limits

Rate limits and concurrency

Category	Default limit	Applies to
read	60 requests / minute	GET endpoints
write	30 requests / minute	Create, update and delete endpoints
generate	10 requests / minute	Generation, clothes extraction and person compose endpoints
source-images	5 requests / minute	POST /api/v1/clothes/source-images
preauth	120 requests / minute per IP	All API requests before API key validation
failed auth	30 failed requests / minute per IP	Missing, malformed or invalid API keys
generation concurrency	3 active requests	Parallel POST /api/v1/generations requests per account

Generation

Prompt contract

Try-on generation is not a raw single-sentence prompt by default. The API composes a production prompt that preserves identity, applies the selected clothing or accessory, controls pose and composition, and asks for realistic lighting and integration.

template

Default. Send scene, activity and optional style fields. prompt becomes extra instruction.

preset

Uses Prompt Gallery text by promptPresetId, then appends your prompt as an instruction.

raw

Advanced mode. The prompt you send is used as the full provider prompt.

Edits are intentionally simpler: send one source image through imageUrl, jobId or clothId plus one edit prompt such as “change the coat to navy” or “show the person skiing”.

{
  "promptMode": "template",
  "scene": "modern hotel lobby with warm daylight",
  "activity": "walking toward camera while carrying the selected bag",
  "composition": "full-body head-to-toe shot",
  "prompt": "premium editorial look, item clearly visible"
}

Workflow

Typical integration flow

Create person

POST /api/v1/persons

Upload one to three person reference images.

Compose person

POST /api/v1/persons/{personId}/compose

Create the 1x3 person composite used by try-on generation.

Add clothes

POST /api/v1/clothes/source-imagesPOST /api/v1/clothes

Extract product images from a page, then store or extract the chosen item.

Generate or edit

POST /api/v1/generationsPOST /api/v1/edits

Poll GET /api/v1/jobs/{id}; use GET /api/v1/history for completed images.

Reference

Account

GET/api/v1/me

Return the authenticated user, subscription state and workspace ownership.

read

Request Example

curl https://vtry.ai/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "user": {
    "id": "117575112934514240688",
    "email": "[email protected]"
  },
  "subscription": {
    "planId": "pro",
    "planLabel": "Pro",
    "status": "active",
    "cancelAtPeriodEnd": false,
    "renewsAt": "2026-06-12T00:00:00.000Z"
  },
  "workspace": {
    "ownerId": "117575112934514240688",
    "isWorkspaceOwner": true
  }
}

Reference

Prompt Presets

GET/api/v1/prompt-presets

List the same try-on prompt presets used by Prompt Gallery.

read

Notes

Use a preset id with POST /api/v1/generations as promptPresetId.
Preset text is returned for transparency; generation requests still compose the final prompt server-side.

Request Example

curl https://vtry.ai/api/v1/prompt-presets \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "presets": [
    {
      "id": "modern-gray-studio",
      "title": "Modern Gray Studio",
      "category": "Studio Fashion",
      "text": "Edit the provided reference image(s)..."
    }
  ],
  "categories": [
    {
      "name": "Studio Fashion",
      "prompts": [
        {
          "id": "modern-gray-studio",
          "title": "Modern Gray Studio",
          "text": "Edit the provided reference image(s)..."
        }
      ]
    }
  ]
}

Reference

People

GET/api/v1/persons

List people in the authenticated workspace.

read

Request Example

curl https://vtry.ai/api/v1/persons \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "persons": [
    {
      "id": "pr_abc123",
      "name": "alice",
      "coverUrl": "https://..."
    }
  ]
}

POST/api/v1/persons

Create a person and upload the first reference image set.

write

Content-Type: multipart/form-data

Request Body

Name	Type	Required	Description
`name`	`string`	yes	Person name. It is normalized to a storage-safe slug.
`files`	`image file[]`	one input required	One to three image files. Repeat the files field for multiple uploads.
`imageUrl or image_url`	`string`	one input required	Remote direct image URL. Use this instead of files.
`sourcePageUrl or source_page_url`	`string`	no	Original page URL used as the referer when fetching imageUrl.

Notes

Send either files or imageUrl. Do not send both.
A person can have at most three reference images.

Request Example

curl https://vtry.ai/api/v1/persons \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=alice" \
  -F "files=@/absolute/path/front.jpg" \
  -F "files=@/absolute/path/side.jpg"

curl https://vtry.ai/api/v1/persons \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=alice" \
  -F "imageUrl=https://example.com/person.jpg"

Response Example

{
  "person": {
    "id": "pr_abc123",
    "name": "alice"
  },
  "files": [
    {
      "key": "persons/.../alice/uuid.jpg",
      "url": "https://...",
      "fileName": "front.jpg",
      "contentType": "image/jpeg",
      "size": 345678
    }
  ],
  "remaining": 1
}

PATCH/api/v1/persons/{personId}

Rename a person.

write

Content-Type: application/json

Path Parameters

Name	Type	Required	Description
`personId`	`string`	yes	Person id returned by GET /api/v1/persons or POST /api/v1/persons.

Request Body

Name	Type	Required	Description
`name or newName`	`string`	yes	New person name. It is normalized to a storage-safe slug.

Request Example

curl -X PATCH https://vtry.ai/api/v1/persons/pr_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"alice-new"}'

Response Example

{
  "person": {
    "id": "pr_abc123",
    "name": "alice-new"
  },
  "moved": 3
}

DELETE/api/v1/persons/{personId}

Delete a person and all uploaded reference images.

write

Path Parameters

Name	Type	Required	Description
`personId`	`string`	yes	Person id returned by the persons endpoints.

Request Example

curl -X DELETE https://vtry.ai/api/v1/persons/pr_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "person": {
    "id": "pr_abc123",
    "name": "alice"
  },
  "deleted": 3
}

GET/api/v1/persons/{personId}/images

List signed URLs for a person reference image set.

read

Path Parameters

Name	Type	Required	Description
`personId`	`string`	yes	Person id returned by the persons endpoints.

Request Example

curl https://vtry.ai/api/v1/persons/pr_abc123/images \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "person": {
    "id": "pr_abc123",
    "name": "alice"
  },
  "images": [
    {
      "key": "persons/.../alice/uuid.jpg",
      "url": "https://..."
    }
  ]
}

POST/api/v1/persons/{personId}/images

Add reference images to an existing person.

write

Content-Type: multipart/form-data

Path Parameters

Name	Type	Required	Description
`personId`	`string`	yes	Person id returned by the persons endpoints.

Request Body

Name	Type	Required	Description
`files`	`image file[]`	one input required	One or more image files. Repeat the files field for multiple uploads.
`imageUrl or image_url`	`string`	one input required	Remote direct image URL. Use this instead of files.
`sourcePageUrl or source_page_url`	`string`	no	Original page URL used as the referer when fetching imageUrl.

Notes

Send either files or imageUrl. Do not send both.
The total image count for the person cannot exceed three.

Request Example

curl https://vtry.ai/api/v1/persons/pr_abc123/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@/absolute/path/third-reference.jpg"

curl https://vtry.ai/api/v1/persons/pr_abc123/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "imageUrl=https://example.com/person-reference.jpg" \
  -F "sourcePageUrl=https://example.com/lookbook-page"

Response Example

{
  "person": {
    "id": "pr_abc123",
    "name": "alice"
  },
  "files": [
    {
      "key": "persons/.../alice/uuid.jpg",
      "url": "https://...",
      "fileName": "third-reference.jpg",
      "contentType": "image/jpeg",
      "size": 234567
    }
  ],
  "remaining": 0
}

DELETE/api/v1/persons/{personId}/images

Delete one reference image from a person.

write

Content-Type: application/json or query string

Path Parameters

Name	Type	Required	Description
`personId`	`string`	yes	Person id returned by the persons endpoints.

Query Parameters

Name	Type	Required	Description
`key`	`string`	yes if no JSON body	Storage key returned by GET /api/v1/persons/{personId}/images.

Request Body

Name	Type	Required	Description
`key`	`string`	yes if no query key	Storage key returned by GET /api/v1/persons/{personId}/images.

Request Example

curl -X DELETE https://vtry.ai/api/v1/persons/pr_abc123/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"key":"persons/.../alice/uuid.jpg"}'

curl -X DELETE "https://vtry.ai/api/v1/persons/pr_abc123/images?key=persons/.../alice/uuid.jpg" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "person": {
    "id": "pr_abc123",
    "name": "alice"
  },
  "deletedKey": "persons/.../alice/uuid.jpg"
}

POST/api/v1/persons/{personId}/compose

Create or refresh the person composite image used by generation requests.

generate

Content-Type: application/json

Path Parameters

Name	Type	Required	Description
`personId`	`string`	yes	Person id returned by the persons endpoints.

Request Body

Name	Type	Required	Description
`model`	`"NanoBanana" \| "NanoBanana2"`	yes	Model used to compose the person image. NanoBanana2 requires a paid plan.

Notes

The person must already have at least one uploaded reference image.
The response returns a requestId. Poll GET /api/v1/jobs/{id} for queued jobs.

Request Example

curl https://vtry.ai/api/v1/persons/pr_abc123/compose \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"model":"NanoBanana"}'

Response Example

{
  "requestId": "req_123",
  "personId": "pr_abc123"
}

Reference

Clothes

GET/api/v1/clothes

List clothes in the authenticated workspace.

read

Query Parameters

Name	Type	Required	Description
`page`	`integer`	no	Page number. Default is 1.
`pageSize`	`integer`	no	Items per page. Default is 8, maximum is 100.

Request Example

curl "https://vtry.ai/api/v1/clothes?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "clothes": [
    {
      "id": "cl_abc123",
      "imageUrl": "https://...",
      "sourceUrl": "https://example.com/product"
    }
  ],
  "page": 1,
  "total": 1,
  "totalPages": 1
}

POST/api/v1/clothes

Add clothes from a direct image or generate a clean clothes packshot from an image.

generate

Content-Type: multipart/form-data

Request Body

Name	Type	Required	Description
`mode`	`"direct" \| "extract"`	yes	direct stores the input image as-is. extract generates a clean product image.
`file`	`image file`	one input required	Local image file. Use this instead of imageUrl.
`imageUrl or image_url`	`string`	one input required	Remote direct image URL. Use this instead of file.
`sourcePageUrl or source_page_url`	`string`	no	Original product/page URL kept as source metadata and referer.
`prompt, userPrompt or user_prompt`	`string`	no	Extra instruction for extract mode, for example "black leather jacket".
`model`	`"NanoBanana" \| "NanoBanana2"`	yes for extract	Model for extract mode. Do not send model with direct mode.
`resolution`	`"1K" \| "2K" \| "4K"`	no	Only supported when model is NanoBanana2. Default is 1K.

Notes

For product pages, first call POST /api/v1/clothes/source-images, then submit one returned imageUrl here.
The response returns a requestId. Poll GET /api/v1/jobs/{id}.

Request Example

curl https://vtry.ai/api/v1/clothes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "mode=direct" \
  -F "imageUrl=https://example.com/dress.jpg" \
  -F "sourcePageUrl=https://example.com/product-page"

curl https://vtry.ai/api/v1/clothes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "mode=extract" \
  -F "model=NanoBanana2" \
  -F "resolution=2K" \
  -F "prompt=black evening dress" \
  -F "file=@/absolute/path/input.jpg"

Response Example

{
  "requestId": "req_123"
}

DELETE/api/v1/clothes/{clothId}

Delete one clothes item.

write

Path Parameters

Name	Type	Required	Description
`clothId`	`string`	yes	Clothes id returned by GET /api/v1/clothes.

Request Example

curl -X DELETE https://vtry.ai/api/v1/clothes/cl_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "clothId": "cl_abc123",
  "deletedKey": "clothes/.../uuid.jpg"
}

POST/api/v1/clothes/source-images

Extract candidate image URLs from a product, outfit or landing page.

source-images

Content-Type: application/json

Request Body

Name	Type	Required	Description
`url, pageUrl, sourcePageUrl or source_page_url`	`string`	yes	HTTP or HTTPS page URL. Direct image URLs are accepted and returned as directImage.
`limit`	`integer`	no	Maximum image count to return. Default is 12, minimum is 1, maximum is 20.

Request Example

curl https://vtry.ai/api/v1/clothes/source-images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://en.zalando.de/outfits/r8afeDGeTVq/",
    "limit": 8
  }'

Response Example

{
  "inputUrl": "https://en.zalando.de/outfits/r8afeDGeTVq/",
  "sourceType": "page",
  "pageTitle": "Outfit",
  "images": [
    {
      "imageUrl": "https://...",
      "sourcePageUrl": "https://en.zalando.de/outfits/r8afeDGeTVq/",
      "title": null,
      "width": 1200,
      "height": 1600,
      "position": 1
    }
  ]
}

Reference

Generations

POST/api/v1/generations

Queue a virtual try-on generation using one composed person image and one or more clothes/accessory items.

generate

Content-Type: application/json

Request Body

Name	Type	Required	Description
`model`	`"NanoBanana" \| "NanoBanana2"`	yes	Generation model. NanoBanana2 requires a paid plan.
`prompt`	`string`	no	In template or preset mode, this is an extra scene/activity instruction. In raw mode, this is the complete provider prompt.
`promptMode`	`"template" \| "preset" \| "raw"`	no	Default is template. preset uses promptPresetId/title. raw sends prompt as-is for advanced users.
`promptPresetId or promptPresetTitle`	`string`	no	Prompt Gallery preset to use, for example modern-gray-studio. If provided, promptMode defaults to preset.
`scene`	`string`	no	Template mode location, for example "a ski resort terrace with snowy mountains".
`activity`	`string`	no	Template mode action, for example "holding the burgundy bag while walking toward camera".
`composition`	`string`	no	Template mode framing override. You can also use cameraAngle and cameraDistance.
`cameraAngle, cameraDistance, lighting, expression, mood`	`string`	no	Optional template controls for camera, lighting, expression and tone.
`personId`	`string`	yes	Person id returned by GET /api/v1/persons.
`clothesIds`	`string[]`	yes	One or more clothes ids returned by GET /api/v1/clothes. NanoBanana supports up to 2, NanoBanana2 supports up to 7.
`aspectRatio`	`"auto" \| "21:9" \| "16:9" \| "3:2" \| "4:3" \| "5:4" \| "1:1" \| "4:5" \| "3:4" \| "2:3" \| "9:16"`	no	Output aspect ratio. NanoBanana2 defaults to 9:16.
`resolution`	`"1K" \| "2K" \| "4K"`	no	Only supported with NanoBanana2. Default is 1K.
`syncMode`	`boolean`	no	Provider sync flag. The API still returns a requestId.
`outputFormat`	`"jpeg" \| "png"`	no	Output file format.
`numImages`	`integer`	no	1 to 4 for NanoBanana. Must be 1 for NanoBanana2.

Notes

The selected person must have a generated composite cover image. If not, call POST /api/v1/persons/{personId}/compose first.
Default template mode builds a full production prompt with identity preservation, wardrobe/accessory fidelity, pose, lighting, integration and photorealistic constraints.
Use promptMode raw only when you already provide the full production prompt yourself.
The response returns the final prompt for transparency. Poll GET /api/v1/jobs/{id}.

Request Example

curl https://vtry.ai/api/v1/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "NanoBanana2",
    "prompt": "make the person look like they are leaving a business hotel lobby",
    "scene": "modern hotel lobby with warm daylight near the entrance",
    "activity": "walking toward the camera while naturally carrying the selected bag",
    "composition": "full-body head-to-toe shot, straight-on camera, item clearly visible",
    "personId": "pr_abc123",
    "clothesIds": ["cl_abc123"],
    "aspectRatio": "9:16",
    "resolution": "2K",
    "outputFormat": "jpeg",
    "numImages": 1
  }'

curl https://vtry.ai/api/v1/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "NanoBanana",
    "promptMode": "preset",
    "promptPresetId": "city-walk-pose",
    "prompt": "show a relaxed city walk with the selected jacket fully visible",
    "personId": "pr_abc123",
    "clothesIds": ["cl_abc123"],
    "aspectRatio": "9:16"
  }'

Response Example

{
  "requestId": "req_123",
  "personId": "pr_abc123",
  "clothesIds": ["cl_abc123"],
  "promptMode": "template",
  "prompt": "Edit the provided reference image(s)..."
}

Reference

Edits

POST/api/v1/edits

Queue a simple image edit from a gallery job, clothes item or direct image URL.

generate

Content-Type: application/json

Request Body

Name	Type	Required	Description
`model`	`"NanoBanana" \| "NanoBanana2"`	no	Default is NanoBanana. NanoBanana2 supports resolution and requires a paid plan.
`prompt`	`string`	yes	Single edit instruction, for example "change the jacket color to navy" or "show the person skiing".
`imageUrl`	`string`	one source required	Direct image URL to edit.
`jobId`	`string`	one source required	Gallery/history job id returned by generation, edit or history endpoints.
`clothId`	`string`	one source required	Clothes id returned by GET /api/v1/clothes.
`aspectRatio`	`"auto" \| "21:9" \| "16:9" \| "3:2" \| "4:3" \| "5:4" \| "1:1" \| "4:5" \| "3:4" \| "2:3" \| "9:16"`	no	Output aspect ratio. NanoBanana2 defaults to 9:16.
`resolution`	`"1K" \| "2K" \| "4K"`	no	Only supported with NanoBanana2. Default is 1K.
`outputFormat`	`"jpeg" \| "png"`	no	Output file format.
`saveAsClothes`	`boolean`	no	When source is clothId, also save the edited result into the clothes library. Default is false.

Notes

Provide exactly one of imageUrl, jobId or clothId.
Use jobId to edit a generated gallery image. Use clothId to edit a stored clothes/accessory image.
The response returns a requestId. Poll GET /api/v1/jobs/{id}.

Request Example

curl https://vtry.ai/api/v1/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "NanoBanana2",
    "jobId": "req_123",
    "prompt": "add a natural smile while preserving the same identity and outfit",
    "aspectRatio": "9:16",
    "resolution": "2K",
    "outputFormat": "jpeg"
  }'

curl https://vtry.ai/api/v1/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "clothId": "cl_abc123",
    "prompt": "change the bag color to deep navy while keeping the same shape and material"
  }'

Response Example

{
  "requestId": "req_456",
  "source": {
    "type": "job",
    "id": "req_123"
  },
  "prompt": "add a natural smile while preserving the same identity and outfit"
}

Reference

Jobs and History

GET/api/v1/jobs/{id}

Read a queued, processing, completed or failed job.

read

Path Parameters

Name	Type	Required	Description
`id`	`string`	yes	requestId returned by compose, clothes, generation or edit endpoints.

Request Example

curl https://vtry.ai/api/v1/jobs/req_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "id": "req_123",
  "status": "COMPLETED",
  "prompt": "High-end editorial fashion campaign",
  "imageUrl": "https://...",
  "imageKey": "generations/.../req_123.jpg",
  "sourceUrl": null,
  "error": null,
  "parameters": {
    "model": "banana",
    "resolution": "2K"
  },
  "createdAt": "2026-05-12T20:00:00.000Z",
  "updatedAt": "2026-05-12T20:00:10.000Z",
  "response": {}
}

GET/api/v1/history

Page through generated image history.

read

Query Parameters

Name	Type	Required	Description
`page`	`integer`	no	Page number. Default is 1.
`pageSize`	`integer`	no	Items per page. Default is 20, maximum is 100.
`kind`	`"images" \| "all"`	no	images hides clothes/person utility jobs. all includes every job. Default is images.

Request Example

curl "https://vtry.ai/api/v1/history?page=1&pageSize=20&kind=images" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "jobs": [
    {
      "id": "req_123",
      "prompt": "High-end editorial fashion campaign",
      "imageUrl": "https://...",
      "imageKey": "generations/.../req_123.jpg",
      "sourceUrl": null,
      "parameters": {
        "model": "banana"
      },
      "status": "COMPLETED",
      "createdAt": "2026-05-12T20:00:00.000Z",
      "updatedAt": "2026-05-12T20:00:10.000Z",
      "response": {}
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1,
  "totalPages": 1
}

Responses

Error format

Errors use a stable JSON shape with a machine-readable code and human-readable message.

Common HTTP statuses are 400 for validation errors, 401 for missing or invalid API keys, 403 for forbidden plan access, 404 for missing resources, 429 for rate limits and 500 or 502 for upstream or configuration failures.

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "validationFailed",
    "message": "Request validation failed",
    "details": {
      "fields": {
        "personId": ["personId is required"]
      }
    }
  }
}