Swap Model API

Change the model in an existing photo while the clothing stays exactly as shot — describe the new model, keep the look.

POST/v1/generateworkflow: swap_models-v1

One endpoint serves every workflow — this page documents swap_models-v1, the current version. Credits are debited at submission (1 cr standard, 3 cr pro); a failed generation is refunded automatically. Earlier versions of this endpoint, if any, keep being served under their own names.

Parameter	Value for this workflow
workflow	"swap_models-v1" required
model_image	Reference model — one public HTTPS URL.required
fields.modeldescription	New model. The new model, e.g. "red-haired woman in her 30s, freckles". Leave it out to let the AI choose.
ratio	auto · 9:16 · 1:1 · 3:4 · 2:3 · 4:3 · 4:5 · 16:9 · 21:9 · 5:4 · 3:2
tier	"standard" (1 cr) or "pro" (3 cr)
webhook_url	Optional — we POST the outcome here when the generation settles. Without it, poll the URL returned in the response until the status settles.

Example request

curl -X POST https://thenewblack.ai/api/v1/generate \
  -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "swap_models-v1",
    "model_image": "https://example.com/model.jpg",
    "fields": {
      "modeldescription": "red-haired woman in her 30s, freckles"
    },
    "ratio": "auto",
    "tier": "standard"
  }'

Example response

Poll /v1/generations/{id} (or receive the webhook) until the generation settles:

// 200 OK
{
  "generation_id": "3f1c9a6e-...",
  "workflow": "swap_models",
  "status": "succeeded",
  "result": {
    "type": "image",
    "url": "https://.../result.webp",
    "thumbnail": "https://.../thumb.webp"
  }
}

Results are stored for 48 hours — copy them to your own storage. Authentication, errors and webhooks are documented in the full API reference.

Frequently asked questions

What does the swap model endpoint change?

Only the person: the new model follows your prompt while the garment, its fit and the framing stay faithful to the input photo.

How is this different from reimagining the scene?

Swap Model keeps the photo and replaces the model; Reimagine Model rebuilds the whole scene — pose, background, light — around the same garment.

How much does it cost?

1 credit on the standard tier, 3 on pro. Credits come with plans and packs; a failed generation is always refunded.

Affiliation & Blog

Contact

Legal