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 (8)

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.

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"
}

Account (3)

The account as its AI agent reads it, for your own program: everything in one reading, what it spent and received, and its Visual DNA profiles 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 (5)

A tech pack whole — pages, sections, data — read and written back, exactly as the account's AI agent does it. The list and the PDF export live in the Creations catalogue above. 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.

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." }

AI agents (10)

Talk to the account's AI agents exactly as in the app — keys with the agentsscope, Business plan and above. An agent has one thread: a message sent here appears in its chat, marked with your key's name, and the agent works with the same tools, the same permissions and the same credits as when you write to it yourself. Its permissions are set in the app and only read here. Its calendar — what it does later or again — and the account's Files are read and written through the same door.

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

curl -X POST "https://thenewblack.ai/api/v1/agents/3f1c9a6e-.../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 the agent 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/agents/3f1c9a6e-.../messages?since=2026-09-09T15:02:11Z" \
  -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX"

{
  "agent": { "id": "3f1c9a6e-...", "name": "Mila", "busy": false, "awaiting": null },
  "messages": [
    { "role": "tool", "results": [
        { "kind": "media", "id": "8b2d...", "url": "https://cloud.thenewblack.ai/.../8b2d.webp", "type": "image", "status": "done" },
        { "kind": "post", "id": "p_44...", "platform": "instagram", "status": "to_validate", "at": "2026-09-10T09:00:00Z" }
    ] },
    { "role": "agent", "kind": "answer", "text": "Three visuals are ready; the Instagram post waits in Posts › To validate.", "results": [] }
  ]
}

When the agent needs your answer before going on, its message is typed question and carries the replies it expects (options); the agent's state reads awaiting: "answer". Your next message is the answer. A post or a Shopify visual keeps living after the message — read its current state through /v1/publish/{id} and /v1/shopify/products.

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.

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 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 DNA and everything in the Creations catalogue), agents (talk to the AI agents, their 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." } }

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" \
  -d '{
    "workflow": "product_to_model-v1",
    "prompt": "AI model wearing the handbag, studio light",
    "tier": "standard",
    "ratio": "4:5",
    "product_images": ["https://example.com/handbag.jpg"],
    "webhook_url": "https://example.com/hooks/tnb"
  }'

// 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.

// 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.