Image Generation API

The freeform door: create any fashion visual from a prompt, or edit up to three reference images with instructions.

POST/v1/generateworkflow: freeform_image-v1

One endpoint serves every workflow — this page documents freeform_image-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	"freeform_image-v1" required
prompt	Describe the creation or the change — English works best.
reference_images	Reference images — up to 3 public HTTPS URLs.
ratio	auto · 9:16 · 1:1 · 4:5 · 3:4 · 2:3 · 16:9 · 4:3 · 3:2 · 5:4 · 21:9
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": "freeform_image-v1",
    "prompt": "Editorial flat-lay of a fall capsule wardrobe, warm light",
    "reference_images": ["https://example.com/reference.jpg"],
    "ratio": "4:3",
    "tier": "standard"
  }'

Example response

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

// 200 OK
{
  "generation_id": "3f1c9a6e-...",
  "workflow": "freeform_image",
  "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 is the freeform image endpoint for?

Anything the specialised workflows don't cover: moodboards, campaign visuals, lookbook imagery, edits guided by up to three reference images.

Can it edit existing images?

Yes — pass reference image URLs and describe the change; the references guide the generation.

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