Flat Lay API
From any garment photo to a styled flat-lay product shot, laid out and lit like a catalogue page.
From $0.054 per image · 1 credit on the standard tier
How it works
1. Create an API key
Sign up and create a key in your profile, under API. It starts with
tnb_live_and goes in theAuthorizationheader. Creating a key needs no plan.2. Send the request
One
POST /v1/generatewith the workflowimage_to_flat_lay-v1and your pictures as public HTTPS URLs. Every value below is one this endpoint accepts.curl -X POST https://thenewblack.ai/api/v1/generate \ -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON' { "workflow": "image_to_flat_lay-v1", "garment_image": "https://example.com/garment.jpg", "fields": { "garmenttorecreate": "the denim jacket" }, "ratio": "1:1", "tier": "standard" } JSONconst res = await fetch("https://thenewblack.ai/api/v1/generate", { method: "POST", headers: { Authorization: `Bearer ${process.env.TNB_API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ "workflow": "image_to_flat_lay-v1", "garment_image": "https://example.com/garment.jpg", "fields": { "garmenttorecreate": "the denim jacket" }, "ratio": "1:1", "tier": "standard" }), }); const { generation_id, poll } = await res.json();import os, requests res = requests.post( "https://thenewblack.ai/api/v1/generate", headers={"Authorization": f"Bearer {os.environ['TNB_API_KEY']}"}, json={ "workflow": "image_to_flat_lay-v1", "garment_image": "https://example.com/garment.jpg", "fields": { "garmenttorecreate": "the denim jacket", }, "ratio": "1:1", "tier": "standard", }, ) generation_id = res.json()["generation_id"]npx @thenewblack/cli generate image_to_flat_lay \ --garment_image ./garment.jpg \ --garmenttorecreate 'the denim jacket' \ --ratio 1:1 \ --tier standard \ --wait --out results/
3. Get the result
The call answers at once with a
generation_id. PollGET /v1/generations/{id}until the status settles, or send awebhook_urland we POST the outcome to it.// 202 Accepted { "generation_id": "3f1c9a6e-...", "status": "running", "poll": "/api/v1/generations/3f1c9a6e-..." } // GET /v1/generations/3f1c9a6e-... → 200 OK { "generation_id": "3f1c9a6e-...", "workflow": "image_to_flat_lay", "status": "succeeded", "result": { "type": "image", "url": "https://.../result.webp", "thumbnail": "https://.../thumb.webp" } }Results stay 48 hours on our URL: copy them to your own storage. Authentication, errors and webhooks are documented in the full API reference.
Parameters
/v1/generateworkflow: image_to_flat_lay-v1One endpoint serves every workflow; this page documents image_to_flat_lay-v1, the current version. Earlier versions, if any, keep being served under their own names.
| Parameter | Value for this workflow |
|---|---|
| workflow | "image_to_flat_lay-v1" required |
| garment_image | Product image — one public HTTPS URL.required |
| fields.garmenttorecreate | Product to recreate. Which product in the photo to lay flat, e.g. "the denim jacket" or "the scarf". |
| ratio | 1:1 · 9:16 · 2:3 · 3:4 · 3:2 · 4:3 |
| tier | "standard" (1 cr), "pro" (3 cr) or "ultra" (7 cr) — a 4K picture, from the Pro plan |
| 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. |
Pricing
| Tier | Credits | What it makes | From |
|---|---|---|---|
| standard | 1 cr | 1K resolution image + fast generation | $0.054 |
| pro | 3 cr | 2K resolution image + thinking process before generating | $0.16 |
| ultra | 7 cr | 4K resolution image + deep thinking process before generating · from the Pro plan | $0.38 |
Credits are debited when the request is accepted, a fixed price per generation; a failed generation is refunded automatically. Dollar prices are at the best credit price, $0.054 a credit (Enterprise, billed yearly). Credits come with plans and packs; new accounts start with free credits.
From Claude and from the terminal
The same workflow is the image_to_flat_lay tool of our MCP server for Claude, and tnb generate image_to_flat_lay in our command line (the CLI tab above), with the same parameters and the same prices.
Frequently asked questions
What does the flat lay endpoint return?
The garment from your photo re-rendered as a top-down flat-lay packshot on a clean surface.
How much does it cost?
1 credit per generation on the standard tier, 3 on pro, 7 on ultra: a fixed price per generation. At $0.054 a credit (Enterprise, billed yearly), that is $0.054 per image on standard. Credits come with plans and packs; a failed generation is always refunded.
Other endpoints: Virtual Try-On API · AI Fashion Models API · Fashion Design API · Reimagine Model API · Swap Model API · AI Stylist API · all endpoints