mcp

Generate an image from a text prompt. Returns a hosted URL plus cost and balance. Slow models (mode "async" in list_models) return a j_… job id instead — poll it with check_job.

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "What to draw"
    },
    "model": {
      "type": "string",
      "description": "Model id from list_models",
      "default": "nano-banana-2"
    },
    "aspect_ratio": {
      "type": "string",
      "description": "e.g. \"16:9\" (default 1:1). Ratios are per-model — list_models names the ones verified for each. Gemini models take a fixed set (no 4:1 or wider); the budget fal models compute any bounded W:H, so use one of those for banner shapes — up to 4:1 / 1:4, beyond which the derived strip gets too thin to send. Every fal model is 1K-only, so that is the practical bound."
    },
    "resolution": {
      "type": "string",
      "enum": [
        "1K",
        "2K",
        "4K"
      ],
      "description": "Output tier (default 1K); supported tiers and prices per model are in list_models"
    },
    "overlay": {
      "oneOf": [
        {
          "type": "string",
          "const": "default",
          "description": "Apply your saved brand kit (set with PUT /v1/brand-kit)"
        },
        {
          "type": "object",
          "description": "Optional brand overlay composited into a corner after generation. Provide EITHER text OR logo_id (an uploaded brand logo), not both.",
          "properties": {
            "text": {
              "type": "string",
              "description": "Handle to render, ≤64 chars, single line (mutually exclusive with logo_id)"
            },
            "logo_id": {
              "type": "string",
              "description": "A logo uploaded via POST /v1/logos (mutually exclusive with text)"
            },
            "logo_style": {
              "type": "string",
              "enum": [
                "sticker",
                "shadow",
                "outline",
                "none"
              ],
              "description": "Logo treatment (logo_id only). RECOMMENDED default \"sticker\": crisp die-cut border + drop shadow, legible on any photo. \"shadow\": drop shadow only (use when the logo already contrasts the scene). \"outline\": border only, flat cut-out. \"none\": bare logo, its own alpha only (use only for a pre-processed logo on a controlled background)."
            },
            "position": {
              "type": "string",
              "enum": [
                "top-left",
                "top-right",
                "bottom-left",
                "bottom-right"
              ],
              "description": "default bottom-right"
            },
            "font": {
              "type": "string",
              "enum": [
                "space-grotesk",
                "inter",
                "jetbrains-mono"
              ],
              "description": "text only; default space-grotesk"
            },
            "weight": {
              "type": "number",
              "enum": [
                400,
                500,
                700
              ],
              "description": "text only; default 700"
            },
            "size": {
              "type": "string",
              "enum": [
                "s",
                "m",
                "l"
              ],
              "description": "text cap-height or logo width; default m"
            },
            "color": {
              "type": "string",
              "description": "text only; \"auto\" (default) or #RRGGBB"
            },
            "opacity": {
              "type": "number",
              "description": "0.2–1.0, default 0.9"
            },
            "margin": {
              "description": "\"safe\" (default) or a non-negative px number"
            }
          }
        }
      ]
    }
  },
  "required": [
    "prompt"
  ]
}

Edit a previously generated image by its img_… id with a natural-language instruction.

{
  "type": "object",
  "properties": {
    "image": {
      "type": "string",
      "description": "img_… id of a previous generation"
    },
    "instruction": {
      "type": "string",
      "description": "What to change"
    },
    "model": {
      "type": "string",
      "default": "nano-banana-2"
    },
    "aspect_ratio": {
      "type": "string",
      "description": "Omit to keep the source image's shape. If set, it is per-model — see list_models."
    },
    "resolution": {
      "type": "string",
      "enum": [
        "1K",
        "2K",
        "4K"
      ],
      "description": "Output tier; defaults to the source image's"
    },
    "overlay": {
      "oneOf": [
        {
          "type": "string",
          "const": "default",
          "description": "Apply your saved brand kit (set with PUT /v1/brand-kit)"
        },
        {
          "type": "object",
          "description": "Optional brand overlay composited into a corner after generation. Provide EITHER text OR logo_id (an uploaded brand logo), not both.",
          "properties": {
            "text": {
              "type": "string",
              "description": "Handle to render, ≤64 chars, single line (mutually exclusive with logo_id)"
            },
            "logo_id": {
              "type": "string",
              "description": "A logo uploaded via POST /v1/logos (mutually exclusive with text)"
            },
            "logo_style": {
              "type": "string",
              "enum": [
                "sticker",
                "shadow",
                "outline",
                "none"
              ],
              "description": "Logo treatment (logo_id only). RECOMMENDED default \"sticker\": crisp die-cut border + drop shadow, legible on any photo. \"shadow\": drop shadow only (use when the logo already contrasts the scene). \"outline\": border only, flat cut-out. \"none\": bare logo, its own alpha only (use only for a pre-processed logo on a controlled background)."
            },
            "position": {
              "type": "string",
              "enum": [
                "top-left",
                "top-right",
                "bottom-left",
                "bottom-right"
              ],
              "description": "default bottom-right"
            },
            "font": {
              "type": "string",
              "enum": [
                "space-grotesk",
                "inter",
                "jetbrains-mono"
              ],
              "description": "text only; default space-grotesk"
            },
            "weight": {
              "type": "number",
              "enum": [
                400,
                500,
                700
              ],
              "description": "text only; default 700"
            },
            "size": {
              "type": "string",
              "enum": [
                "s",
                "m",
                "l"
              ],
              "description": "text cap-height or logo width; default m"
            },
            "color": {
              "type": "string",
              "description": "text only; \"auto\" (default) or #RRGGBB"
            },
            "opacity": {
              "type": "number",
              "description": "0.2–1.0, default 0.9"
            },
            "margin": {
              "description": "\"safe\" (default) or a non-negative px number"
            }
          }
        }
      ]
    }
  },
  "required": [
    "image",
    "instruction"
  ]
}

Render a typeset card from a template — a finished, on-brand social image (quote card, post card) in about two seconds. Cheaper and more legible than generating type with a model. Get the templates and their slots from list_templates.

{
  "type": "object",
  "properties": {
    "template": {
      "type": "string",
      "description": "Template id from list_templates, e.g. \"quote-card\""
    },
    "slots": {
      "type": "object",
      "description": "The template's slot values, e.g. { \"quote\": \"…\", \"handle\": \"@you\" }. Image slots take an asset id from upload_asset, or \"default\" for your brand kit."
    },
    "size": {
      "type": "string",
      "enum": [
        "16:9",
        "1:1",
        "4:5",
        "og"
      ],
      "description": "default 16:9"
    },
    "style": {
      "description": "Leave unset for the template default, \"auto\" for a random combination that avoids your last one, \"brand\" for your saved colours, or an object of style axes.",
      "oneOf": [
        {
          "type": "string",
          "enum": [
            "auto",
            "brand"
          ]
        },
        {
          "type": "object",
          "properties": {
            "palette": {
              "type": "string"
            },
            "font": {
              "type": "string"
            },
            "layout": {
              "type": "string"
            },
            "shadow": {
              "type": "boolean",
              "description": "crisp offset shadow behind the type"
            }
          }
        }
      ]
    },
    "scale": {
      "type": "number",
      "enum": [
        1,
        2,
        3
      ],
      "description": "device pixel ratio; 2 default, 3 costs $0.01 more"
    },
    "overlay": {
      "oneOf": [
        {
          "type": "string",
          "const": "default",
          "description": "Apply your saved brand kit (set with PUT /v1/brand-kit)"
        },
        {
          "type": "object",
          "description": "Optional brand overlay composited into a corner after generation. Provide EITHER text OR logo_id (an uploaded brand logo), not both.",
          "properties": {
            "text": {
              "type": "string",
              "description": "Handle to render, ≤64 chars, single line (mutually exclusive with logo_id)"
            },
            "logo_id": {
              "type": "string",
              "description": "A logo uploaded via POST /v1/logos (mutually exclusive with text)"
            },
            "logo_style": {
              "type": "string",
              "enum": [
                "sticker",
                "shadow",
                "outline",
                "none"
              ],
              "description": "Logo treatment (logo_id only). RECOMMENDED default \"sticker\": crisp die-cut border + drop shadow, legible on any photo. \"shadow\": drop shadow only (use when the logo already contrasts the scene). \"outline\": border only, flat cut-out. \"none\": bare logo, its own alpha only (use only for a pre-processed logo on a controlled background)."
            },
            "position": {
              "type": "string",
              "enum": [
                "top-left",
                "top-right",
                "bottom-left",
                "bottom-right"
              ],
              "description": "default bottom-right"
            },
            "font": {
              "type": "string",
              "enum": [
                "space-grotesk",
                "inter",
                "jetbrains-mono"
              ],
              "description": "text only; default space-grotesk"
            },
            "weight": {
              "type": "number",
              "enum": [
                400,
                500,
                700
              ],
              "description": "text only; default 700"
            },
            "size": {
              "type": "string",
              "enum": [
                "s",
                "m",
                "l"
              ],
              "description": "text cap-height or logo width; default m"
            },
            "color": {
              "type": "string",
              "description": "text only; \"auto\" (default) or #RRGGBB"
            },
            "opacity": {
              "type": "number",
              "description": "0.2–1.0, default 0.9"
            },
            "margin": {
              "description": "\"safe\" (default) or a non-negative px number"
            }
          }
        }
      ]
    }
  },
  "required": [
    "template",
    "slots"
  ]
}

Upload an image (PNG or JPEG, ≤5 MB) as a reusable asset — an avatar for a card, for example. Returns an ast_… id to pass into a template slot.

{
  "type": "object",
  "properties": {
    "data": {
      "type": "string",
      "description": "data URI or bare base64, e.g. \"data:image/png;base64,…\""
    },
    "kind": {
      "type": "string",
      "enum": [
        "avatar",
        "logo",
        "photo",
        "image"
      ],
      "description": "what the image is for; \"avatar\" for a card byline"
    }
  },
  "required": [
    "data",
    "kind"
  ]
}

List available image models with pricing and latency.

{
  "type": "object",
  "properties": {}
}

List card templates with their slots, style axes and exact price.

{
  "type": "object",
  "properties": {}
}

Show the current prepaid balance in USD.

{
  "type": "object",
  "properties": {}
}

Check an async generation job by its j_… id. Slow models (mode "async" in list_models) return a job instead of an image — poll this until it succeeds or fails.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "j_… id returned by generate_image / edit_image"
    }
  },
  "required": [
    "job_id"
  ]
}