AI Fashion Clothing API

Workflows catalogue (77)

Every studio workflow is callable by its versioned endpoint name. The route returns the live catalogue — named image parameters, fields, variants, formats and prices; the table below is rendered from the same data.

Publishing catalogue (5)

Send what you create where it sells, by API — keys with the publish scope. One documentation page per platform.

Creations catalogue (4)

Read back what the account has created — keys with the read scope. Every listing accepts ?project=<id> to filter by project. PDF exports return a JSON { url } — public but unguessable, the same regime as every creation URL.

Account (6)

The account as its AI agent reads it, for your own program: everything in one reading, the credit balance, what it spent and received, its invoices, and its Visual styles with the analysis the vision model wrote. read scope; nothing is debited.

curl "https://thenewblack.ai/api/v1/account" \
  -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX"

{
  "id": "a1e259ae-...", "username": "maison-k", "credits": 206.5,
  "team": { "role": "leader", "members": [{ "id": "3edf...", "username": "lea" }] },
  "brand_dna": [{ "id": "7c1a...", "name": "SS27", "focus": "womenswear", "analysed": true, "references": 12 }],
  "library": { "creations": 1000, "favourites": 3, "archived": 3 },
  "projects": [{ "id": "7763...", "name": "Linen capsule", "creations": 41, "archived": 0, "last_creation": "2026-09-11T16:02:00Z" }],
  "counts": { "shopify_products": 18, "techpacks": 4 },
  "techpacks": [{ "id": "8363...", "name": "Custom Print Crew Neck T-Shirt", "pages": 2, "project": null, "template": false, "origin": "ai", "updated_at": "2026-09-10T09:14:00Z" }]
}

Tech packs (9)

The tech packs and the moodboards: listed, exported as a PDF, and a tech pack whole — pages, sections, data — read and written back, exactly as the account's AI agent does it. Reading takes the read scope; writing takes generate, the scope that creates and changes things in the studio. Editing costs nothing; Start with AI costs 1 credit for the reading plus 1 per sketch, like the button.

List, then export — two calls and a downloadable file:

curl "https://thenewblack.ai/api/v1/techpacks" \
  -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX"

{
  "techpacks": [
    {
      "id": "3f1c9a6e-8b21-4f7d-9c1e-2a7b5d4e8f01",
      "name": "Short sleeves",
      "project": "b2cefb2b-3d48-48c1-9f2a-6e1c0d7a9b34",
      "cover": "https://cloud.thenewblack.ai/storage/v1/object/public/media/...",
      "updated_at": "2026-08-21T14:03:22Z"
    }
  ]
}

curl "https://thenewblack.ai/api/v1/techpacks/3f1c9a6e-8b21-4f7d-9c1e-2a7b5d4e8f01/pdf" \
  -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX"

{
  "url": "https://cloud.thenewblack.ai/storage/v1/object/public/media/exports/.../8c4e21d7-....pdf",
  "name": "Short sleeves"
}

Read a section first, then write back the same keys with your changes — never drop a column or a cell the person made. Shapes by kind: header { cells: [{ key, label, value }] }; descriptions { blocks: [{ key, label, body }] }; size_chart and bom { columns: [{ key, label }], rows: [{ <columnKey>: "text" }], unit?, note? }; end_notes { block: { key, label, body } }.

curl -X PUT "https://thenewblack.ai/api/v1/techpacks/3f1c9a6e-.../sections/9a1d..." \
  -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "columns": [{ "key": "item", "label": "Item" }, { "key": "supplier", "label": "Supplier" }],
                  "rows": [{ "item": "Linen 180 g", "supplier": "Libeco" }] } }'

{ "ok": true, "section_id": "9a1d...", "kind": "bom" }

Start with AI takes photos hosted by us — URLs from /v1/media or from a generation — front first; the model writes the header, the description and the size chart, and the BOM stays empty (a supplier is not in a photo). With sketch it draws the flat(s) on the canvas.

curl -X POST "https://thenewblack.ai/api/v1/techpacks/from-photos" \
  -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "images": ["https://cloud.thenewblack.ai/.../front.jpg"], "size_range": "XS-XL", "unit": "cm", "sketch": "front" }'

{ "id": "6b3e...", "status": "done", "note": "Created. Read it (GET /v1/techpacks/{id}) to check the values; the BOM is empty by design." }

Mila - AI Agent (10)

Make Mila work from your own program, exactly as in the app: she uses the studio, the store and the tools for you, with the same permissions and the same credits. Every account has her; keys need the agentsscope. Your message appears in her chat, marked with your key's name, and she answers in the thread.

Send a message, then read the thread until she is free. A message can carry pictures from your gallery (media_ids, from /v1/media); an Idempotency-Key header makes a retry harmless.

curl -X POST "https://thenewblack.ai/api/v1/mila/messages" \
  -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX" \
  -H "Idempotency-Key: order-8812" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Make three on-model visuals of this product and publish them to Instagram.", "media_ids": ["6f2a9c1b-..."] }'

{ "status": "accepted", "task_id": "0c4e...", "message_id": "9a1d...", "created_at": "2026-09-09T15:02:11Z" }

// while Mila works, the same call answers:
{ "status": "working", "task_id": "0c4e...", "since": "2026-09-09T15:02:11Z", "on": "Make three on-model visuals..." }

curl "https://thenewblack.ai/api/v1/mila/messages?since=2026-09-09T15:02:11Z" \
  -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX"

When Mila needs your answer, her message is typed question with the replies she expects (options), and her state reads awaiting: "answer". Your next message is the answer.

Fixed routes

Every route of /v1 besides the workflows — the 77 workflows above are not routes but the bodies one route accepts, POST /v1/generate. Drawn from the same descriptions the OpenAPI document, the CLI and the Claude MCP connector are built from: complete by construction, never typed here.

Introduction

The API is asynchronous, like the studio it drives: you submit a generation, credits are debited atomically at submission, and you collect the result by polling — or let us call your webhook when it settles. A generation that fails is refunded automatically.

Serving several stores or clients? On the Enterprise plan, each one can be a workspace of its own — its own API keys, its own creations — on one plan and one balance, with the usage of each workspace in Team › Usage.

Base URL   https://thenewblack.ai/api/v1
Format     JSON in, JSON out
Auth       Authorization: Bearer tnb_live_...

The whole API is described in OpenAPI 3.1, publicly and without a key, generated at the instant of the call: GET /api/v1/openapi.json — every route, every workflow as a body schema of /generate, every error code. Point a code generator, an agent or an SDK builder at it. The catalogue alone is at GET /api/v1/catalog (every workflow's contract and prices) and GET /api/v1/catalog/presets (the stock preset shelves). The Claude connector and the CLI build themselves from these.

Authentication

Create up to three keys from your account's API / MCP tab. A key needs only a free account, no plan: a new account starts with free credits, enough to make its first calls before choosing a plan. A key is shown once at creation and stored only as a hash — keep it server-side, never in a browser. Keys belong to the paying account: on a team, they spend the leader's credits.

Each key carries scopes chosen at creation: generate (create with the workflows and edit tech packs — spends credits), read (poll generations, list workflows, check credits, read the account, the ledger, the Visual style and everything in the Creations catalogue), agents (talk to Mila, her calendar and the Files — spends credits like the chat), publish (post to connected platforms — Shopify and the social platforms).

curl https://thenewblack.ai/api/v1/credits \
  -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX"

Errors

Errors are JSON with a stable code and a human message:

{ "error": { "code": "insufficient_credits", "message": "Not enough credits — this needs 3." } }

Rate limits

An account starts a set number of generations a minute, through the API, the CLI and the MCP connector together: 30 without a plan or on Starter, 60 on Pro, 120 on Business, 300 on Enterprise. Reading — polling a generation, listing, checking credits — is not counted. Past the limit, POST /v1/generate answers 429 rate_limited with a Retry-After header (seconds to wait), and nothing is charged. Need more for a launch or a store network? Write to us — the limit can be raised for your account.

// 429 Too Many Requests   ·   Retry-After: 12
{ "error": { "code": "rate_limited", "message": "This account starts at most 60 generations a minute on its plan. Try again in 12 s.",
             "retry_after": 12, "limit_per_minute": 60 } }

Create a generation

Requires the generate scope. Credits are debited when the request is accepted; if the balance is short nothing starts and nothing is charged. Returns 202 with the generation id.

curl -X POST https://thenewblack.ai/api/v1/generate \
  -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "workflow": "product_to_model-v1",
  "product_images": [
    "https://example.com/handbag.jpg"
  ],
  "fields": {
    "gender": "Woman",
    "seg_framing": "full body",
    "seg_scene": "a rooftop terrace at dusk"
  },
  "tier": "standard",
  "ratio": "4:5",
  "webhook_url": "https://example.com/hooks/tnb"
}
JSON

// 202 Accepted
{
  "generation_id": "3f1c9a6e-...",
  "status": "running",
  "poll": "/api/v1/generations/3f1c9a6e-..."
}

Retrieve a generation

Requires the read scope. Poll every few seconds until status is succeeded or failed. A failed generation is refunded automatically.

Most images are ready in under a minute — a background removal in seconds, a virtual try-on or a product on a model in about half a minute; videos take longer. The result's URL lives 48 hours: copy the file to your own storage. After that the result is deleted and the call answers expired — unless the creation was opened in the app, which keeps it like any other.

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

Webhooks

Pass webhook_url when creating a generation and we POST the outcome — success or failure — to your endpoint the moment it settles, instead of being polled. Answer with any 2xx; we try once, with a 5-second timeout, and your poll endpoint always remains the source of truth.

// POST to your webhook_url
{
  "generation_id": "3f1c9a6e-...",
  "status": "succeeded",
  "result": { "type": "image", "url": "https://...", "thumbnail": "https://..." }
}

Credits

The account's live balance. Generation costs are per workflow and tier — see the catalogue; video is billed per second of output. Top up or subscribe on the pricing page.

// 200 OK
{ "credits": 142 }

The same capabilities inside a conversation: connect The New Black AI to Claude or ChatGPT as a Model Context Protocol server and generate from your chat — no code, same keys, same credits. The connector builds its tools from the live catalogue. Setup and details on the MCP page.

Building your integration with Claude Code? Install our skill and Claude knows the whole contract — auth, the async loop, every workflow read live from the catalogue, the CLI — before it writes a line:

npx skills add newblackai/claude-skill --skill thenewblack

Command line

The same API as a program — for an AI coding agent (Claude Code, Codex, Cursor), a script, a cron or a CI job. One command per workflow, generated from the live catalogue, and one per route of this page; local pictures uploaded once, --wait and --out do the plumbing. In a conversation, add the connector; in a project of code, install the CLI. Everything on the CLI page.

npx @thenewblack/cli --help
tnb generate virtual_try_on --product_images dress.jpg --model_image model.jpg --ratio 4:5 --wait --out ./renders/

Migrating from the legacy API

When the platform migration completes, the legacy endpoints are retired and answer with a notice pointing here. Keys are not carried over: create a new key from your API / MCP tab, point your integration at /api/v1, and retire the old key with the old endpoints. The concepts are unchanged — submit, poll or webhook, 48-hour storage — with one endpoint now covering every workflow of the studio.