Supermachine

AI image generation with Supermachine — API docs: https://devs.supermachine.art/

⚠️ The docs host and the API host differ by one letter. The documentation is served from devs.supermachine.art (with an s), but requests go to https://dev.supermachine.art (no s). Every path is versioned under /v1. Authentication is a standard bearer token: Authorization: Bearer sk-….

• Actions: Generate Image (text-to-image), Get Generation Result, List Models, Get Account Credits.
• Triggers: none — see below.
• Text in, URLs out. Every input this piece sends is text; nothing uploads image bytes — see the omissions below.

Connection: sign in at supermachine.art/supermachine, open Profile settings → the API tab (page title "API Settings") → Generate API Key, and copy the sk-… value.

⚠️ Most Supermachine plans cannot get a key at all. The app only shows the API tab on Lifetime Deal 3X and above; Lifetime Deal and Lifetime Deal 2X users see "API feature is available for Lifetime Deal 3X and above", and sub-accounts get no API tab whatsoever. If the tab is missing, the plan is the reason — there is nothing to hunt for. A key that is valid but not entitled comes back as FORBIDDEN / HTTP 403, and this piece says so in the error rather than blaming the key.

Notes

• Image generation is asynchronous, and there is no failure status. POST /v1/generate returns only { batchId, method, type, creditsRemaining } — no pixels. The images appear on GET /v1/images?batchId=…, whose documented status enum is exactly two values: generating and completed. There is no failed, so a job that dies is indistinguishable from a slow one and simply stays generating forever. Get Generation Result therefore enforces its own timeout (default 300 s, max 1800 s) and throws a clear "did not complete in time" error rather than letting a flow hang indefinitely. Check the batch in the Supermachine app if that fires.
• Rate limit: 10 requests per minute per API key, sliding window, reported on X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset and with Retry-After plus a retryAfter field in the error body on 429. This is tight enough to shape the whole piece:
  • The docs suggest polling /v1/images every 2 seconds. This piece deliberately does not. At 2 s a single generation issues 30 requests a minute — three times the entire budget, with nothing left for the POST /v1/generate that started it. The polling floor here is 6 seconds (exactly 10 polls a minute) and the default is 10 seconds, which leaves room for the rest of the flow. A value below 6 is clamped up rather than rejected.
  • Most actions return a rateLimit object (limit, remaining, reset) alongside their result, so a flow can see how close it is to the ceiling without spending a request to ask.
• Models are named by title on the way in and by slug on the way out. POST /v1/generate wants the human-readable title — "Supermachine NextGen" — while the image records echo the slug, "supermachine-nextgen". They are not interchangeable and sending the slug is rejected, so the Model dropdown (populated from GET /v1/models) sends title as its value and shows the slug only as a label hint.
• List Models is also the resolution reference. GET /v1/models publishes each model's capabilities (img2img, lora, character, controlnet), its config.guidance / config.steps min/max/default, and config.resolutions[] with { width, height, aspectRatio, isXL, creditCost }. That list is the only published source of truth for what Width/Height Generate Image will accept and what a given size costs. Getting it wrong returns INVALID_RESOLUTION, whose body carries availableResolutions[] — this piece pulls those into the error message because "pick one of these sizes" is the actionable part.
• Four images per batch, max. count is capped at 4; the action rejects a larger number up front rather than paying for a request the API will refuse. Get Generation Result also never reads fewer than 4 results per page, so a whole batch always lands on the page it inspects — a smaller page would report completed after seeing only part of the batch.
• Polling survives a rate limit. By the time a flow polls, the batch is already paid for, so a RATE_LIMITED or INTERNAL_ERROR response mid-poll does not fail the step: the action waits out the retryAfter (never faster than the 6s floor) and asks again, inside the same timeout it started with. Errors that will never resolve — bad key, plan gate, no credits, invalid input — still fail immediately.
• Costs. Image generation is roughly 1–4 credits per image depending on resolution (about 1–2 for common sizes). Use Get Account Credits (GET /v1/user) as a guard step before anything expensive; it also reports plan, gems and totalCredits. INSUFFICIENT_CREDITS (HTTP 402) carries the exact shortfall, e.g. "Not enough credits. Required: 4, Available: 2.5".
• No triggers. The word "webhook" does not appear anywhere in the Supermachine docs — there is no subscription mechanism to register. The only pollable alternative would be "new image in the account", which would fire on every image the user creates by hand in the Supermachine web app as well as on flow output, and would spend a large share of the 10-per-minute budget doing it. This piece ships actions only; start image work from a trigger elsewhere in the flow.
• Nothing that uploads image bytes — scope, not a capability gap. This piece sends text to Supermachine and gets URLs back, and nothing more. That rules out the three file-input tools — POST /v1/tools/upscale, /v1/tools/remove-background and /v1/tools/image-to-prompt — and the img2img and controlnet reference-image inputs on POST /v1/generate. All of them work and are documented; all of them would mean TaskMagic transmitting the user's image data to Supermachine on their behalf, which is deliberately out of scope here. Generate Image is therefore text-to-image only.
• No Face Swap action — deliberate, not an oversight. POST /v1/tools/faceswap (taking faceImage + targetImage) exists and works. It is not exposed here. Supermachine positions itself explicitly as uncensored — its own copy reads "We have no issue with adult content or NSFW generations" — and an automatable face-swap on top of unrestricted generation is a deepfake-capable combination that does not belong in a workflow step. This is a product decision; please do not "fix" it by adding the action.
• No credential-management actions. POST /v1/auth/token-exchange, /v1/auth/regenerate-key and /v1/auth/revoke-key are omitted on purpose: a flow step has no business rotating or revoking the very key it is authenticating with, and a mis-fired run would silently break every other flow on that connection. Manage keys in Profile settings → API.
• Also not shipped: POST /v1/tools/instruct and POST /v1/tools/flux-img2img — both are image-editing tools that take base64 image bytes, so they fall under the same text-only scope as the tools above. Video models are visible through List Models with Type set to Video, but there is no video generation action; /v1/generate is documented against image models here.
• No custom API call action. A passthrough would hand this connection's sk-… key to any URL a flow supplies, and the endpoints people actually automate are covered above.
• Error envelope. Every failure is {"error": {"code", "message"}} with codes UNAUTHORIZED (401), FORBIDDEN (403 — usually the plan gate), NOT_FOUND (404), VALIDATION_ERROR (400), INVALID_RESOLUTION (400, adds availableResolutions[]), INSUFFICIENT_CREDITS (402), RATE_LIMITED (429, adds retryAfter) and INTERNAL_ERROR (500). All of them are mapped to plain-English messages that say what to change; the API key is never included in a thrown message.