Skip to main content
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:
SurfaceWhere to read it
SDK completed resultresult.getMetadata()
Full task (GET /tasks/:id)data.request.metadata
Webhookspayload.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

ConstraintLimit
TypeJSON object (not a string, number, or array at the top level)
Maximum size2 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

  1. You send metadata on the generate request.
  2. Mynth stores it on the task as part of request.
  3. Generation runs as usual. Metadata does not change model selection, billing, or image output.
  4. 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.