Use Destinations

Use the destination option on POST /image/generate when you want each successful image uploaded to storage you control. By default, Mynth only stores images on the Mynth CDN — no destination is required. Skip destinations when the Mynth CDN URL (mynth_url) is enough, or when you re-upload from that URL yourself. Destinations are for output delivery. To send input images into generation, see Upload Input Images.

Pricing

Destination delivery is included with image generation. Mynth does not charge an extra fee for uploading to your destination. You still pay generation cost per successful image. Your storage provider may bill for storage and egress separately.

Create a destination

Create destinations in the destinations dashboard. That is the primary path for most teams.

Open the destinations dashboard.
Create a destination with a slug (name), provider credentials, and path config.
Optionally run a test upload from the dashboard to verify credentials.

The slug is immutable after creation. It must match /^[a-z0-9-]+$/ (1–64 characters): lowercase letters, digits, and dashes only. Supported providers:

Provider `id`	Storage	Secret fields	Notable options
`s3`	Amazon S3 (or S3-compatible)	`access_key_id`, `secret_access_key`	`bucket`, `region`, optional `endpoint`, `force_path_style`
`r2`	Cloudflare R2	`access_key_id`, `secret_access_key`	`account_id`, `bucket`, optional `jurisdiction` (`default`, `eu`, `fedramp`)
`bunny`	Bunny Storage	`password`	`storage_zone`, optional `region` (`de`, `uk`, `ny`, `la`, `sg`, `se`, `br`, `jh`, `syd`)

Management API routes (/destinations) require OAuth login, not API keys. Use the dashboard, or create via REST after OAuth (see below).

Pass a destination on generate

Reference the destination by its slug:

const task = await mynth.image.generate({
  prompt: "Product photo of a ceramic mug on marble",
  model: "google/gemini-3.1-flash-image",
  destination: "my-bucket",
});

const image = task.getImages()[0];
console.log(image?.url); // destination public URL when url_template is set
console.log(image?.mynth_url); // always the Mynth CDN URL
console.log(image?.destination); // { status: "success", name: "my-bucket" }

Set a client-wide default with the SDK constructor or MYNTH_DESTINATION:

const mynth = new Mynth({
  destination: "my-bucket", // or omit and set MYNTH_DESTINATION
});

// Per-request destination overrides the client default
await mynth.image.generate({
  prompt: "Product photo of a ceramic mug on marble",
  model: "google/gemini-3.1-flash-image",
  destination: "staging-bucket",
});

If the slug does not exist for your account, generate validation fails before the task is created.

Read delivery fields on the result

When a destination is requested, each successful image includes delivery fields. Success with url_template configured:

{
  "status": "success",
  "id": "img_...",
  "url": "https://cdn.my-domain.com/images/img_....webp",
  "mynth_url": "https://...",
  "cost": "0.03",
  "size": "1024x1024",
  "destination": {
    "status": "success",
    "name": "my-bucket"
  }
}

Field	Meaning
`url`	Public URL built from `url_template`, or `null` when no `url_template` is set or destination upload failed
`mynth_url`	Always the Mynth CDN URL for a successful image
`destination`	Per-image delivery status for the requested destination

Without url_template, a successful destination upload still stores the object, but url is null. Read mynth_url (or build the public URL yourself from the resolved path). task.urls in the SDK only includes non-null url values. Prefer task.getImages() and read url / mynth_url / destination when you use destinations.

for (const image of task.getImages()) {
  if (image.destination?.status === "success") {
    console.log(image.id, image.url ?? image.mynth_url);
  } else if (image.destination?.status === "failed") {
    console.error(image.id, image.destination.error.code, image.mynth_url);
  }
}

Handle delivery failure

Destination upload runs after the image is generated. Delivery failure does not fail generation. If destination upload fails:

The image result still has status: "success"
mynth_url still points at the Mynth CDN
url is null
destination is:

{
  "status": "failed",
  "name": "my-bucket",
  "error": {
    "code": "DESTINATION_UPLOAD_FAILED",
    "message": "Failed to upload to destination"
  }
}

Error codes:

Code	When
`DESTINATION_INIT_FAILED`	Destination could not be loaded (missing config, secret, or provider init)
`DESTINATION_UPLOAD_FAILED`	Provider upload failed
`DESTINATION_FAILED`	Other delivery error

Optional error fields: message, provider_response. Always check destination.status per image when you depend on your own storage.

Configure path and URL templates

When you create or update a destination, set:

Config field	Required	Purpose
`path_template`	Yes	Object key/path in your bucket or storage zone (max 2048 characters)
`url_template`	No	Public URL for the result `url` field; must include `{path}`

Mynth resolves path_template, uploads the file to that path, then builds url from url_template by substituting {path}. Double slashes in the resulting URL (except after https:) are collapsed to a single slash.

Path template tokens

Token	Resolves to
`{id}`	Mynth image id (for example `img_...`)
`{YYYY}`	Upload year (from the worker clock)
`{MM}`	Month, zero-padded (`01`–`12`)
`{DD}`	Day of month, zero-padded
`{uuid}` / `{uuidv4}`	Random UUID v4
`{uuidv7}`	UUID v7
`{ulid}`	ULID
`{meta.key}`	String value of `metadata.key` from the generate request

Rules:

The output format extension is always appended (.webp, .png, or .jpg). Do not put the extension in path_template.
{meta.key} only substitutes string metadata values. Missing or non-string values become the literal text undefined.
Metadata keys in templates may use letters, digits, and underscores only: {meta.userId}, not {meta.user-id}.

Example:

path_template: /images/{YYYY}/{MM}/{meta.campaign}/{id}
url_template:  https://cdn.my-domain.com/{path}

With metadata: { "campaign": "spring" }, output.format: "webp", and image id img_abc, the object path becomes:

/images/2026/07/spring/img_abc.webp

and url becomes:

https://cdn.my-domain.com/images/2026/07/spring/img_abc.webp

Use Use Metadata when path templates need per-request string values via {meta.key}.

REST example

Generate with a destination (API key auth):

curl https://api.mynth.io/image/generate \
  -X POST \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Product photo of a ceramic mug on marble",
    "model": "google/gemini-3.1-flash-image",
    "destination": "my-bucket"
  }'

Creating a task does not return images immediately. Wait in the SDK, poll task endpoints, or use webhooks — see Async and polling. When the generate task completes, each successful image may include destination as shown above.

Create a destination via API (OAuth)

Management routes require OAuth, not an API key:

curl https://api.mynth.io/destinations \
  -X POST \
  -H "Authorization: Bearer <oauth-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-bucket",
    "provider": {
      "id": "s3",
      "bucket": "my-bucket",
      "region": "us-east-1"
    },
    "secret": {
      "access_key_id": "...",
      "secret_access_key": "..."
    },
    "config": {
      "path_template": "/images/{id}",
      "url_template": "https://cdn.my-domain.com/{path}"
    }
  }'

Other management endpoints (OAuth):

Method	Path	Purpose
`GET`	`/destinations`	List destinations
`GET`	`/destinations/:id`	Get one by id (`dst_...`)
`PUT`	`/destinations/:id`	Update `provider`, `config`, and optionally `secret` (slug cannot change)
`DELETE`	`/destinations/:id`	Delete
`POST`	`/destinations/:id/test`	Upload a test file; body `{ "path": "test/upload.txt" }`

How destinations fit generation

Mynth generates the image and post-processes it (output.format / quality).
Mynth uploads the image to the Mynth CDN and, if destination was set, to your storage in parallel.
The result sets mynth_url to the CDN URL.
If destination upload succeeded, destination.status is "success" and url is the url_template result (or null without url_template).
If destination upload failed, the image remains successful: url is null, mynth_url is still set, and destination reports the error.

Delivery runs once per successfully generated image in the same image.generate task. Completed generate webhooks include per-image destination when a destination was requested.

Generate Images — full generate request options
Use Metadata — request metadata and {meta.key} path tokens
Upload Input Images — inputs for generation, not output storage
Use Webhooks — receive completed results with destination fields

Getting started

Generation

Control and delivery

Image analysis

Integrations

Pricing

Create a destination

Pass a destination on generate

Read delivery fields on the result

Handle delivery failure

Configure path and URL templates

Path template tokens

REST example

Create a destination via API (OAuth)

How destinations fit generation

​Pricing

​Create a destination

​Pass a destination on generate

​Read delivery fields on the result

​Handle delivery failure

​Configure path and URL templates

​Path template tokens

​REST example

​Create a destination via API (OAuth)

​How destinations fit generation

​Related guides

Pricing

Create a destination

Pass a destination on generate

Read delivery fields on the result

Handle delivery failure

Configure path and URL templates

Path template tokens

REST example

Create a destination via API (OAuth)

How destinations fit generation

Related guides