Use Metadata

Use the metadata option on POST /image/generate when you need to carry application identifiers through the task lifecycle. Metadata is optional and omitted by default. Metadata is only available on image generation (image.generate). Content rating and alt text requests do not accept metadata. For the full generate request field list, see Image Generation Request. To receive completed tasks without polling, see Use Webhooks.

Pricing

Metadata is free. Mynth does not charge for attaching or returning metadata.

Attach metadata

Pass a JSON object on the generate request:

const result = await mynth.image.generate({
  prompt: "Packaging concept for a botanical tea brand",
  model: "google/gemini-3.1-flash-image",
  metadata: {
    requestId: "req_123",
    userId: "usr_123",
    campaign: "spring-launch",
  },
});

console.log(result.getMetadata());
// { requestId: "req_123", userId: "usr_123", campaign: "spring-launch" }

Mynth stores the object on the task as request.metadata and returns it unchanged. Nested objects and arrays are allowed as values.

Read metadata back

Metadata is echoed in these places:

Surface	Where to read it
SDK completed result	`result.getMetadata()`
Full task (`GET /tasks/:id`)	`data.request.metadata`
Webhooks	`payload.request.metadata`

GET /tasks/:id/result does not include request, so it does not return metadata. Use the full task endpoint, the SDK, or webhooks when you need it. Webhook example (fields abbreviated):

{
  "event": "task.image.generate.completed",
  "task": { "id": "tsk_..." },
  "request": {
    "prompt": "Packaging concept for a botanical tea brand",
    "model": "google/gemini-3.1-flash-image",
    "metadata": {
      "requestId": "req_123",
      "userId": "usr_123",
      "campaign": "spring-launch"
    }
  },
  "result": {
    "model": "google/gemini-3.1-flash-image",
    "images": []
  }
}

Failed generate webhooks still include request, so metadata is available on both task.image.generate.completed and task.image.generate.failed.

Constraints

Constraint	Limit
Type	JSON object (not a string, number, or array at the top level)
Maximum size	2 KB (`2048` bytes of `JSON.stringify` UTF-8)

If the payload is too large, the API rejects the request with a validation error:

{
  "code": "VALIDATION_ERROR",
  "message": "Metadata cannot exceed 2048 bytes (current size: 2100 bytes)"
}

REST example

curl https://api.mynth.io/image/generate \
  -X POST \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Packaging concept for a botanical tea brand",
    "model": "google/gemini-3.1-flash-image",
    "metadata": {
      "requestId": "req_123",
      "userId": "usr_123",
      "campaign": "spring-launch"
    }
  }'

Creating a task does not return images immediately. Wait in the SDK, poll task endpoints, or use webhooks — see Async and polling. After completion, read metadata from the full task object or the webhook request.

How metadata fits generation

You send metadata on the generate request.
Mynth stores it on the task as part of request.
Generation runs as usual. Metadata does not change model selection, billing, or image output.
Completed and failed deliveries include the same request.metadata you sent.

Common uses:

Map Mynth tasks back to your jobs, users, orders, or database rows
Correlate webhook deliveries without an extra lookup
Pass string keys used by destination path templates as {meta.key} (string values only)

For a full-stack mapping pattern with Convex, see Convex full-stack image generation.

Getting started

Generation

Control and delivery

Image analysis

Integrations

Pricing

Attach metadata

Read metadata back

Constraints

REST example

How metadata fits generation

​Pricing

​Attach metadata

​Read metadata back

​Constraints

​REST example

​How metadata fits generation

Pricing

Attach metadata

Read metadata back

Constraints

REST example

How metadata fits generation