@mynthio/sdk

Official SDK for the Mynth image generation API.

The SDK gives you a typed Mynth client, sync and async generation flows, model metadata, and a Convex webhook helper.

Installation

# Bun
bun add @mynthio/sdk

# pnpm
pnpm add @mynthio/sdk

# npm
npm install @mynthio/sdk

# yarn
yarn add @mynthio/sdk

Quick Start

Set your API key:

MYNTH_API_KEY=mak_...

Create a client:

import Mynth from "@mynthio/sdk";

const mynth = new Mynth();

Generate an image:

const task = await mynth.image.generate({
  prompt: "A fox in a neon-lit city at night",
});

console.log(task.id);
console.log(task.urls);
console.log(task.result?.model);

If you omit model and size, Mynth resolves them automatically. generate() waits for completion and returns a completed task.

Client Options

import Mynth from "@mynthio/sdk";

const mynth = new Mynth({
  apiKey: process.env.MYNTH_API_KEY,
  baseUrl: "https://api.mynth.io",
});

• apiKey: optional if MYNTH_API_KEY is set
• baseUrl: optional override for proxies or tests

Generate vs Generate Async

Generate

generate() polls until the task is completed.

const task = await mynth.image.generate({
  prompt: "Editorial product photo of a matte black coffee grinder",
  model: "black-forest-labs/flux.2-dev",
});

console.log(task.status); // "completed"
console.log(task.urls);

Generate Async

Use generateAsync() when you want to trigger work now and fetch the final task later.

const taskAsync = await mynth.image.generateAsync({
  prompt: "A cinematic fantasy castle on a cliff",
  model: "google/gemini-3.1-flash-image",
});

console.log(taskAsync.id);
console.log(taskAsync.access.publicAccessToken);

const completedTask = await taskAsync.wait();
console.log(completedTask.urls);

taskAsync.access.publicAccessToken is safe to send to the client. It is scoped to that single task, so you can poll task state from the browser without exposing your API key or building your own polling proxy.

You can use it as a Bearer token against:

• GET /tasks/:id/status
• GET /tasks/:id/result

Example:

const taskAsync = await mynth.image.generateAsync({
  prompt: "A cinematic fantasy castle on a cliff",
  model: "google/gemini-3.1-flash-image",
});

const taskId = taskAsync.id;
const pat = taskAsync.access.publicAccessToken;

const status = await fetch(`https://api.mynth.io/tasks/${taskId}/status`, {
  headers: {
    Authorization: `Bearer ${pat}`,
  },
})
  .then((res) => res.json())
  .then((body) => body.data);

if (status.status === "completed") {
  const taskResult = await fetch(`https://api.mynth.io/tasks/${taskId}/result`, {
    headers: {
      Authorization: `Bearer ${pat}`,
    },
  })
    .then((res) => res.json())
    .then((body) => body.data);

  console.log(taskResult.result.images);
}

Request Shape

generate() accepts a typed ImageGenerationRequest. The simplest request is just a prompt:

await mynth.image.generate({
  prompt: "A cozy cabin in a snowy pine forest",
});

You can also pass structured options:

const task = await mynth.image.generate({
  prompt: "Studio portrait of a futuristic fashion model",
  negative_prompt: "blurry, low detail",
  magic_prompt: true,
  model: "google/gemini-3-pro-image-preview",
  size: {
    type: "aspect_ratio",
    aspectRatio: "4:5",
  },
  count: 2,
  output: {
    format: "webp",
    quality: 80,
  },
  webhook: {
    dashboard: false,
    custom: [{ url: "https://your-app.com/api/mynth-webhook" }],
  },
  access: {
    pat: {
      enabled: true,
    },
  },
  rating: {
    mode: "custom",
    levels: [
      { value: "safe", description: "Safe for all audiences" },
      { value: "sensitive", description: "Contains mature or suggestive content" },
    ],
  },
  inputs: [
    "https://example.com/reference-1.jpg",
    {
      type: "image",
      role: "reference",
      source: {
        type: "url",
        url: "https://example.com/reference-2.jpg",
      },
    },
  ],
  metadata: {
    generationId: "gen_123",
    userId: "user_123",
  },
});

access.pat.enabled controls whether the create-task response includes a short-lived Public Access Token for browser-side polling. It defaults to true.

Prompt Options

prompt is the positive text prompt. Use negative_prompt for exclusions and magic_prompt: true to ask Mynth to enhance the prompt before generation.

await mynth.image.generate({
  prompt: "A luxury watch on a marble pedestal",
  negative_prompt: "text, watermark",
  magic_prompt: true,
});

Size Options

size supports:

• presets such as "square", "portrait", "landscape", "portrait_tall", "landscape_wide", and the explicit aspect-ratio preset IDs
• "auto"
• structured auto objects
• structured aspect-ratio objects with an optional scale: "4k"

Supported aspect ratios:

• "1:1"
• "2:3"
• "3:2"
• "3:4"
• "4:3"
• "4:5"
• "5:4"
• "9:16"
• "16:9"
• "21:9"
• "2:1"
• "1:2"

Use scale: "4k" when you want the higher tier and the model supports it.

Examples:

size: "landscape";
size: "auto";
size: { type: "aspect_ratio", aspectRatio: "16:9" };
size: { type: "aspect_ratio", aspectRatio: "4:5", scale: "4k" };
size: { type: "auto", provider: "native" };

Input Images

Use inputs to send reference or init images:

inputs: [
  "https://example.com/input-image.jpg",
  {
    type: "image",
    role: "reference",
    source: {
      type: "url",
      url: "https://example.com/reference-image.jpg",
    },
  },
];

String URLs are a shorthand for image inputs. Structured inputs let you control the role explicitly with "auto", "init", or "reference".

Rating

Enable per-image content rating during generation with rating.

const task = await mynth.image.generate({
  prompt: "A fashion editorial image",
  rating: true, // same result levels as { mode: "nsfw_sfw" }
});

console.log(task.getImages()[0]?.rating?.level); // "sfw" | "nsfw"

For custom labels, pass at least two and at most seven levels:

const task = await mynth.image.generate({
  prompt: "A movie poster",
  rating: {
    mode: "custom",
    levels: [
      { value: "general", description: "Appropriate for all audiences" },
      { value: "teen", description: "Mild mature themes" },
      { value: "adult", description: "Adult-oriented content" },
    ] as const,
  },
});

console.log(task.getImages()[0]?.rating?.level); // "general" | "teen" | "adult"

You can also rate existing image URLs:

const result = await mynth.image.rate({
  mode: "nsfw_sfw",
  urls: ["https://example.com/image.webp"],
});

console.log(result.task.id);
console.log(result.getRatings());

Working With Results

Completed tasks expose a few helpful accessors:

const task = await mynth.image.generate({
  prompt: "An orange cat astronaut on the moon",
  metadata: { source: "readme-example" },
});

console.log(task.id);
console.log(task.status);
console.log(task.isCompleted);
console.log(task.urls);
console.log(task.getImages());
console.log(task.getImages({ includeFailed: true }));
console.log(task.getMetadata());
console.log(task.result?.magic_prompt);

task.urls and task.getImages() return only successful images by default. task.result?.images may also include failed image entries.

Available Models

The SDK exports AVAILABLE_MODELS, which mirrors the current model list and capability metadata shipped with the package.

import { AVAILABLE_MODELS } from "@mynthio/sdk";

const model = AVAILABLE_MODELS.find((item) => item.id === "google/gemini-3.1-flash-image");

console.log(model);
// {
//   id: "google/gemini-3.1-flash-image",
//   label: "Nano Banana 2",
//   capabilities: ["inputs", "4k", "native_enhance_prompt", "native_auto_size"]
// }

Current model IDs include:

• auto
• alibaba/qwen-image-2.0
• alibaba/qwen-image-2.0-pro
• bytedance/seedream-5.0-lite
• black-forest-labs/flux.1-dev
• black-forest-labs/flux-1-schnell
• black-forest-labs/flux.2-dev
• black-forest-labs/flux.2-pro
• black-forest-labs/flux.2-flex
• black-forest-labs/flux.2-max
• black-forest-labs/flux.2-klein-4b
• google/gemini-3.1-flash-image
• google/gemini-3-pro-image-preview
• imagineart/imagineart-1.5-pro
• openai/gpt-image-2
• john6666/bismuth-illustrious-mix
• purplesmartai/pony-diffusion-v6-xl
• recraft/recraft-v4
• recraft/recraft-v4-pro
• tongyi-mai/z-image-turbo
• wan/wan2.6-image
• xai/grok-imagine-image

TypeScript Types

The SDK exports the request and payload types via MynthSDKTypes.

import type { MynthSDKTypes } from "@mynthio/sdk";

const request: MynthSDKTypes.ImageGenerationRequest = {
  prompt: "Minimal product shot of a glass bottle",
  model: "auto",
};

Convex Integration

The package includes a Convex HTTP action helper for webhook verification and event routing.

import { mynthWebhookAction } from "@mynthio/sdk/convex";

export const mynthWebhook = mynthWebhookAction({
  imageTaskCompleted: async (payload, { context }) => {
    console.log("Completed task:", payload.task.id);
    console.log(payload.result.images);
  },
  imageTaskFailed: async (payload) => {
    console.error("Mynth task failed:", payload.task.id);
  },
});

Set MYNTH_WEBHOOK_SECRET in your environment, or pass webhookSecret explicitly as the second argument to mynthWebhookAction(...).

Error Handling

generate() and generateAsync() may throw MynthAPIError if the initial request fails. Polling can also throw task-specific errors:

import {
  MynthAPIError,
  TaskAsyncFetchError,
  TaskAsyncTaskFailedError,
  TaskAsyncTaskFetchError,
  TaskAsyncTimeoutError,
  TaskAsyncUnauthorizedError,
} from "@mynthio/sdk";

try {
  const taskAsync = await mynth.image.generateAsync({ prompt: "A watercolor landscape" });

  const task = await taskAsync.wait();
  console.log(task.urls);
} catch (error) {
  if (error instanceof MynthAPIError) {
    console.error(error.status, error.code, error.message);
  } else if (error instanceof TaskAsyncTimeoutError) {
    console.error("Task polling timed out");
  } else if (error instanceof TaskAsyncUnauthorizedError) {
    console.error("Task access was denied");
  } else if (error instanceof TaskAsyncFetchError) {
    console.error("Repeated status fetch failures");
  } else if (error instanceof TaskAsyncTaskFailedError) {
    console.error("The generation task failed");
  } else if (error instanceof TaskAsyncTaskFetchError) {
    console.error("Fetching the completed task failed");
  }
}

Documentation

For product documentation and API guides, visit docs.mynth.io.

Contributing

See CONTRIBUTING.md for development setup, Conventional Commits guidance, and release process notes.

License

MIT