How do I get started with The New Black AI API?
Updated on November 9, 2026
- 1.Create your account on thenewblack.ai. No plan is needed, and the free credits at signup cover your first calls.
- 2.Open your profile and go to the API / MCP / CLI tab.
- 3.Press Create API key, give it a name if you like, such as production, and keep the scopes you need ticked.
- 4.Press Create key, then Copy. The key is shown once and never again.
- 5.Make your first call: GET /v1/credits, with the header Authorization: Bearer followed by your key. The answer is your balance.
- 6.Start a generation with POST /v1/generate, then read the result at the address it returns.
Your key and its scopes
You can hold up to three keys. Only a hash is stored, so a lost key is replaced, not recovered: delete it and create another. Keep the key on your server, never in a browser or an app people download. On a team, keys belong to the account owner and spend the owner's credits.
Each key carries the scopes you ticked when you created it:
| Scope | What it opens |
|---|---|
| Generate | create with the workflows and edit tech packs, spends credits |
| Read | poll generations, list workflows, check credits, read the account, the ledger, your creations and tech packs |
| Publish | post to your connected platforms, Shopify and the social networks |
| Mila | talk to your AI agent, its calendar and your Files, spends credits like the chat |
A call without the right scope answers 403 missing_scope.
Your first generation
POST /v1/generate takes a JSON body. A product on a model, for example:
| Field | Example | What it is |
|---|---|---|
| workflow | product_to_model-v1 | the workflow and its version, from the catalogue |
| product_images | a public image address | the photo of your product, in its named slot |
| fields | gender, framing, scene | the workflow's own fields, as in its Studio panel |
| tier | standard | standard, pro or ultra where the workflow offers it |
| ratio | 4:5 | one of the workflow's ratios |
| webhook_url | your endpoint | optional, where we post the outcome |
The answer is 202 with a generation_id and a poll address. Read GET /v1/generations/ followed by that id every few seconds until the status is succeeded or failed, or let your webhook receive the outcome. Most images are ready in under a minute; videos take longer. The result's address lives 48 hours: copy the file to your own storage.
Credits
Credits are debited when the request is accepted, at the same price as the Generate button in the Studio: Product to Model is 1 credit on Standard, 3 on Pro and 7 on Ultra, and video is billed per second. If the balance is short, nothing starts and nothing is charged: the answer is 402 insufficient_credits. A failed generation is refunded automatically. Pro needs a plan and Ultra images need the Pro plan, as in the Studio. Every workflow's price is in the catalogue and in How many credits does each workflow cost?
Rate limits
An account starts a set number of generations a minute, through the API, the command line and the MCP connector together: 30 without a plan or on Starter, 60 on Pro, 120 on Business, 300 on Enterprise. Reading is not counted. Past the limit the answer is 429 rate_limited with a Retry-After header in seconds, and nothing is charged.
The OpenAPI document
The whole API is described in OpenAPI 3.1 at https://thenewblack.ai/api/v1/openapi.json, public and readable without a key. It is assembled at the moment you request it: every route, every workflow as its own body schema of /v1/generate, every error code. Point a code generator or a coding agent at it for a typed client that is never out of date. See the OpenAPI document.
Errors
| Status | Code | What it means |
|---|---|---|
| 401 | missing_key or invalid_key | no key, or an unknown or deleted one |
| 402 | insufficient_credits | the balance cannot cover the generation |
| 403 | missing_scope | the key lacks the scope for this call |
| 404 | unknown_workflow or not_found | no such workflow, or no such generation on this account |
| 429 | rate_limited | wait the Retry-After seconds |
| 502 | generation_refused | the job was refused, any credit is refunded |
Good to know
- The full reference, with every endpoint, the live catalogue of workflows and copyable examples, is on the API and integrations page.
- No code at all: the same page shows the MCP connector for AI assistants and the command line.
- Your AI agent by API: with the scope that opens it, you can send it requests and put tasks on its calendar. See How do I schedule recurring tasks for the AI agent?