Changelog

A request that failed validation used to come back in the validator's own shape: { data, error, success } on /image/* and /video/*, { success, errors } elsewhere, with no code and your request echoed back. Now every request error has the same body:

{
  "code": "VALIDATION_ERROR",
  "message": "model \"flux.2-pro\" is not supported. Did you mean \"black-forest-labs/flux.2-pro\"? See https://mynth.io/models, or GET /models, for the model IDs.",
  "issues": [{ "path": ["model"], "message": "model \"flux.2-pro\" is not supported. …" }]
}

message states every problem, so it is safe to show as it is. issues has one { path, message } per field that failed the schema. An unknown model suggests the closest id, and an invalid size lists the forms it takes.

Two new codes cover requests that never reach validation:

• INVALID_JSON (400) for a body that is not valid JSON, with the parser's position. It used to be plain text.
• UNSUPPORTED_MEDIA_TYPE (415) for a JSON endpoint called without Content-Type: application/json, or POST /image/upload without multipart/form-data. Such a body used to be read as empty, so the error blamed a missing prompt.

A size a pinned model cannot produce, such as 16:9_4k on a model without 4k, is now rejected at create with 400 VALIDATION_ERROR and the size to use instead. It used to be accepted and then fail the task with CAPABILITY_NOT_SUPPORTED. With model: "auto" nothing changes.

Other messages got more specific too: input, resolution, duration, and audio errors list what the model accepts, UNAUTHORIZED says what is wrong with the credential, balance and spending-limit errors state the amounts, upload errors name the file, and a 404 names the route.

If your code reads error, errors, or data from a 400, read code, message, and issues instead. MynthAPIError in the SDK now carries issues and a useful message, and the CLI exits with 2 for both new codes. See errors.

INSUFFICIENT_BALANCE used to return 422 and SPENDING_LIMIT_EXCEEDED used to return 429. Both now return 402 Payment Required. The code and message in the body are the same.

The old 429 looked like a rate limit, so HTTP clients that retry 429 kept resending a request that could only succeed once the key's period rolled over. Now a 429 means back off and retry, and a 402 means top up, raise the cap, or wait for the period to reset.

If your code checks code, nothing changes. If it checks the status, look for 402 where you looked for 422 or 429:

if (error instanceof MynthAPIError && error.status === 402) {
  // error.code is INSUFFICIENT_BALANCE or SPENDING_LIMIT_EXCEEDED
}

The CLI still exits with 4 for both codes, and now also for any other 402.

output.format on POST /image/generate now decides the encoding. Pass png, jpg, or webp and Mynth converts the image before delivering it. Leave it out and you get whatever the provider returned.

{
  "model": "black-forest-labs/flux.2-pro",
  "prompt": "A futuristic cityscape at sunset with flying cars",
  "output": { "format": "webp" }
}

Every successful image in the result now carries a format field, so you can read what was actually delivered instead of inferring it from the URL.

Two fields went away. output.quality is gone, and each format encodes at its own default. Per-image cost is gone from the result as well, so read the task-level cost instead.

Results also report magic_prompt again when magic prompt rewrites your prompt. It had been dropped from the payload.

Two new image analysis calls. review scores an image for quality issues, and alt writes short, descriptive alt text. Both work on any image, whether Mynth generated it or not.

import Mynth from "@mynthio/sdk";

const mynth = new Mynth();

const review = await mynth.image.review({ url: "https://..." });
const { alt } = await mynth.image.alt({ url: "https://..." });

Both are CLI commands too, mynth image review and mynth image alt. The SDK also ships webhook helpers for Next.js and TanStack Start.

mynth.image.rate and mynth.image.alt now take a single image instead of a batch. Calls that passed an array must make one call per image. The batched form is gone from the SDK and the CLI.