# TollNode machine contract

> Every node is an HTTP POST priced in USDC on Base via x402. Unpaid calls return 402 with the exact price. Paid calls settle only on success.

## Status codes

- 200: success; the payment settled. The PAYMENT-RESPONSE header carries the transaction.
- 400: the body failed the node's schema. Not charged.
- 401: (API key only) the key is wrong or revoked. Not charged.
- 402: payment required (or the payment could not be verified). Not charged.
- 403: this wallet is blocked after an unpaid call. Not charged.
- 404 / 503: unknown or paused node. Not charged.
- 409: this payment was already used. Not charged again.
- 502 / 504: the node failed or timed out. Not charged.

## How to pay

- Send a POST with a JSON body to the node URL. Without payment you get HTTP 402 with the exact price in USDC on Base (PAYMENT-REQUIRED header, plus a JSON body for older x402 clients). Where an option such as resolution or quality changes the price, the 402 quotes the price for the option in your body; omit it and you get (and pay for) the default.
- Sign the payment with any x402 client and retry with the PAYMENT-SIGNATURE header (legacy X-PAYMENT also works).
- TollNode checks the payment, runs the node, and settles only if the result is usable. Failed, empty or timed-out calls are never charged, so there is nothing to refund.
- No account, no API key, no subscription needed.

## Or use an API key

Alternative for apps and teams: create an account at https://tollnode.com/sign-up, add funds in USDC on Base at https://tollnode.com/account, create an API key and send it as "Authorization: Bearer tn_live_…" to the same node URL. Same prices, deducted from the balance only when a call succeeds. A too-low balance returns 402 with a top-up link; a bad or revoked key returns 401.

## ElevenLabs v3 expressive speech

POST https://tollnode.com/api/v1/nodes/elevenlabs-v3-speech
Price: $0.136 USDC per successful call
Category: Audio

ElevenLabs' most expressive voices for narration and characters. Up to 1,000 characters per call, one flat price. Returns an MP3.

Input schema:
```json
{
  "type": "object",
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 1000,
      "minLength": 1,
      "description": "Up to 1,000 characters"
    },
    "speed": {
      "type": "number",
      "maximum": 1.2,
      "minimum": 0.7
    },
    "voice": {
      "enum": [
        "Rachel",
        "Drew",
        "Clyde",
        "Paul",
        "Aria",
        "Domi",
        "Dave",
        "Roger",
        "Fin",
        "Sarah",
        "James",
        "Jane",
        "Juniper",
        "Arabella",
        "Hope",
        "Bradford",
        "Reginald",
        "Austin",
        "Kuon",
        "Blondie",
        "Priyanka",
        "Alexandra",
        "Monika",
        "Mark",
        "Grimblewood"
      ],
      "type": "string"
    },
    "language_code": {
      "type": "string",
      "pattern": "^[a-z]{2}$",
      "description": "Two-letter language code, default en"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "text": "The barrier lifts. Your agent paid the toll.",
  "voice": "Aria"
}
```

Example response:
```json
{
  "audio": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Qwen3 text-to-speech

POST https://tollnode.com/api/v1/nodes/speech-qwen3
Price: $0.028 USDC per successful call
Category: Audio

Nine natural voices in 10 languages, steerable with a plain-language style instruction (tone, pace, emotion). Up to 1,000 characters per call.

Input schema:
```json
{
  "type": "object",
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 1000,
      "minLength": 1,
      "description": "Up to 1,000 characters"
    },
    "style": {
      "type": "string",
      "maxLength": 300,
      "description": "How to say it, e.g. 'warm and calm, slightly slower'"
    },
    "voice": {
      "enum": [
        "Aiden",
        "Dylan",
        "Eric",
        "Ono_anna",
        "Ryan",
        "Serena",
        "Sohee",
        "Uncle_fu",
        "Vivian"
      ],
      "type": "string"
    },
    "language": {
      "enum": [
        "auto",
        "Chinese",
        "English",
        "Japanese",
        "Korean",
        "French",
        "German",
        "Italian",
        "Spanish",
        "Portuguese",
        "Russian"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "text": "Every request pays its own toll. No accounts, no keys, just results.",
  "style": "confident radio announcer, warm, measured pace",
  "voice": "Ryan"
}
```

Example response:
```json
{
  "audio": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Realtime text-to-speech

POST https://tollnode.com/api/v1/nodes/speech-realtime
Price: $0.035 USDC per successful call
Category: Audio

Natural speech in 15+ languages with low latency. Up to 1,000 characters per call, one flat price. Returns an MP3 (or WAV/OGG/FLAC).

Input schema:
```json
{
  "type": "object",
  "required": [
    "text"
  ],
  "properties": {
    "text": {
      "type": "string",
      "maxLength": 1000,
      "minLength": 1,
      "description": "Up to 1,000 characters"
    },
    "voice": {
      "type": "string",
      "maxLength": 40,
      "description": "Voice name, default Ashley"
    },
    "language": {
      "enum": [
        "auto",
        "en",
        "zh",
        "ja",
        "ko",
        "ru",
        "it",
        "es",
        "pt",
        "fr",
        "de",
        "pl",
        "nl",
        "hi",
        "he",
        "ar"
      ],
      "type": "string"
    },
    "audio_format": {
      "enum": [
        "mp3",
        "wav",
        "ogg_opus",
        "flac"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "text": "Welcome to TollNode. Pay per call, no sign-up."
}
```

Example response:
```json
{
  "audio": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Song generation with vocals

POST https://tollnode.com/api/v1/nodes/music-song
Price: $0.042 USDC per successful call
Category: Audio

A full song with vocals from your lyrics and a style description. One flat price per song. Returns an MP3.

Input schema:
```json
{
  "type": "object",
  "required": [
    "lyrics",
    "style"
  ],
  "properties": {
    "style": {
      "type": "string",
      "maxLength": 300,
      "minLength": 3,
      "description": "Genre, mood, instruments, vocal style"
    },
    "lyrics": {
      "type": "string",
      "maxLength": 600,
      "minLength": 10,
      "description": "Song lyrics; use [verse] and [chorus] tags"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "style": "upbeat indie rock, driving drums, warm male vocals",
  "lyrics": "[verse]\nHeadlights on the open road\nEvery mile a story told\n[chorus]\nPay the toll and let it roll"
}
```

Example response:
```json
{
  "audio": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Background removal

POST https://tollnode.com/api/v1/nodes/remove-background
Price: $0.026 USDC per successful call
Category: Image

Cut the subject out of any image and get a clean transparent PNG. Hair and soft edges kept.

Input schema:
```json
{
  "type": "object",
  "required": [
    "image"
  ],
  "properties": {
    "image": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Image URL (https)"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "image": "https://tollnode.com/examples/nano-banana-2-1-2k.jpg"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Crisp image upscaler

POST https://tollnode.com/api/v1/nodes/upscale-crisp
Price: $0.010 USDC per successful call
Category: Image

Upscale an image while sharpening edges and fine detail, without the plastic look. One flat price.

Input schema:
```json
{
  "type": "object",
  "required": [
    "image"
  ],
  "properties": {
    "image": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Image URL (https)"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "image": "https://tollnode.com/examples/image-flash.jpg"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## FLUX 1.1 Pro Ultra 4MP images

POST https://tollnode.com/api/v1/nodes/flux-1-1-pro-ultra
Price: $0.082 USDC per successful call
Category: Image

Up to 4-megapixel images with FLUX 1.1 Pro Ultra, plus a raw mode for natural, less processed photography.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "raw": {
      "type": "boolean",
      "description": "Natural, less processed look"
    },
    "seed": {
      "type": "integer"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "aspect_ratio": {
      "enum": [
        "21:9",
        "16:9",
        "3:2",
        "4:3",
        "5:4",
        "1:1",
        "4:5",
        "3:4",
        "2:3",
        "9:16",
        "9:21"
      ],
      "type": "string",
      "description": "Aspect ratio, default 1:1"
    },
    "output_format": {
      "enum": [
        "jpg",
        "png"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "raw": true,
  "prompt": "aerial photo of a mountain pass toll plaza in snow"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## FLUX 1.1 Pro image generation

POST https://tollnode.com/api/v1/nodes/flux-1-1-pro
Price: $0.055 USDC per successful call
Category: Image

Black Forest Labs' workhorse pro model: excellent image quality, prompt adherence and variety, fast.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "16:9",
        "3:2",
        "2:3",
        "4:5",
        "5:4",
        "9:16",
        "3:4",
        "4:3"
      ],
      "type": "string",
      "description": "Aspect ratio, default 1:1"
    },
    "output_format": {
      "enum": [
        "webp",
        "jpg",
        "png"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "editorial photo of a highway at blue hour, long exposure light trails"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## FLUX 3 image generation and editing

POST https://tollnode.com/api/v1/nodes/flux-3-image
Price: from $0.029 USDC per successful call (by resolution: 1k $0.034, 2k $0.069, 4k $0.411, 1.5k $0.049, 768sq $0.029; default 1k)
Category: Image

Black Forest Labs' latest image model: generate from a prompt or edit with up to 10 reference images, from 768px to 4K.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "images": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      },
      "maxItems": 10,
      "description": "Reference or source image URLs (https), optional"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "resolution": {
      "enum": [
        "768sq",
        "1k",
        "1.5k",
        "2k",
        "4k"
      ],
      "type": "string",
      "description": "Sets the price. Default 1k"
    },
    "aspect_ratio": {
      "enum": [
        "auto",
        "21:9",
        "2:1",
        "16:9",
        "3:2",
        "4:3",
        "5:4",
        "1:1",
        "4:5",
        "3:4",
        "2:3",
        "9:16"
      ],
      "type": "string",
      "description": "Aspect ratio, default auto"
    },
    "output_format": {
      "enum": [
        "webp",
        "jpg",
        "png"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "macro photo of a dew-covered road sign",
  "resolution": "1k"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## FLUX Dev image generation

POST https://tollnode.com/api/v1/nodes/flux-dev
Price: $0.035 USDC per successful call
Category: Image

The popular 12B open-weight FLUX model: strong quality at a low price, with optional image-to-image.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer"
    },
    "image": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Optional source image for image-to-image"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "guidance": {
      "type": "number",
      "maximum": 10,
      "minimum": 0
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "16:9",
        "21:9",
        "3:2",
        "2:3",
        "4:5",
        "5:4",
        "3:4",
        "4:3",
        "9:16",
        "9:21"
      ],
      "type": "string",
      "description": "Aspect ratio, default 1:1"
    },
    "output_format": {
      "enum": [
        "webp",
        "jpg",
        "png"
      ],
      "type": "string"
    },
    "prompt_strength": {
      "type": "number",
      "maximum": 1,
      "minimum": 0,
      "description": "How far to move from the source image"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a retro-futuristic toll gate made of neon tubes, synthwave"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## FLUX Kontext Max image editing

POST https://tollnode.com/api/v1/nodes/flux-kontext-max
Price: $0.109 USDC per successful call
Category: Image

The premium Kontext editor: maximum quality text-guided edits and the best typography of the FLUX family.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "input_image": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Image to edit (https URL); omit to generate"
    },
    "aspect_ratio": {
      "enum": [
        "match_input_image",
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4",
        "3:2",
        "2:3",
        "4:5",
        "5:4",
        "21:9",
        "9:21"
      ],
      "type": "string",
      "description": "Aspect ratio, default match_input_image"
    },
    "output_format": {
      "enum": [
        "jpg",
        "png"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "turn this into a 1950s travel poster",
  "input_image": "https://tollnode.com/examples/restore-photo-after.jpg"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## FLUX Kontext Pro image editing

POST https://tollnode.com/api/v1/nodes/flux-kontext-pro
Price: $0.055 USDC per successful call
Category: Image

Edit an image with a text instruction while keeping the subject consistent. One flat price per edit.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt",
    "input_image"
  ],
  "properties": {
    "seed": {
      "type": "integer"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "input_image": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Image to edit (https URL)"
    },
    "aspect_ratio": {
      "enum": [
        "match_input_image",
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4",
        "3:2",
        "2:3"
      ],
      "type": "string",
      "description": "Aspect ratio, default match_input_image"
    },
    "output_format": {
      "enum": [
        "jpg",
        "png"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "make it night time with neon lights",
  "input_image": "https://tollnode.com/opengraph-image"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Fast 2x / 4x upscaler

POST https://tollnode.com/api/v1/nodes/upscale-fast
Price: $0.004 USDC per successful call
Category: Image

The classic fast upscaler: enlarge an image 2x or 4x, with optional face enhancement. The cheapest way to add resolution.

Input schema:
```json
{
  "type": "object",
  "required": [
    "image"
  ],
  "properties": {
    "image": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Image URL (https)"
    },
    "scale": {
      "enum": [
        2,
        4
      ],
      "type": "integer",
      "description": "Upscale factor, default 4"
    },
    "face_enhance": {
      "type": "boolean",
      "description": "Improve faces, default false"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "image": "https://tollnode.com/examples/image-flash.jpg",
  "scale": 4
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Fast text-to-image

POST https://tollnode.com/api/v1/nodes/image-flash
Price: $0.006 USDC per successful call
Category: Image

Turn a text prompt into one 1-megapixel image in about two seconds. Returns a WebP image URL.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What the image should show"
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "16:9",
        "21:9",
        "3:2",
        "2:3",
        "4:5",
        "5:4",
        "3:4",
        "4:3",
        "9:16",
        "9:21"
      ],
      "type": "string",
      "description": "Optional, default 1:1"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a yellow highway toll booth at dusk, photo"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/f95beacd-44d5-47d3-a24c-26525bc0bb6c/0"
  ]
}
```

## GPT Image 1.5 generation and editing

POST https://tollnode.com/api/v1/nodes/gpt-image-1-5
Price: from $0.019 USDC per successful call (by quality: low $0.019, high $0.185, medium $0.069; default medium)
Category: Image

OpenAI's GPT Image 1.5: better instruction following, transparent backgrounds and edits from reference images.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "quality": {
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "type": "string",
      "description": "Sets the price. Default medium"
    },
    "background": {
      "enum": [
        "auto",
        "transparent",
        "opaque"
      ],
      "type": "string"
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "3:2",
        "2:3"
      ],
      "type": "string",
      "description": "Aspect ratio, default 1:1"
    },
    "input_images": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      },
      "maxItems": 6,
      "description": "Reference or source image URLs (https), optional"
    },
    "output_format": {
      "enum": [
        "png",
        "jpeg",
        "webp"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a sticker of a smiling toll booth mascot, transparent background",
  "quality": "low",
  "background": "transparent"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## GPT Image 2 generation and editing

POST https://tollnode.com/api/v1/nodes/gpt-image-2
Price: from $0.018 USDC per successful call (by quality: low $0.018, high $0.174, medium $0.065; default medium)
Category: Image

OpenAI's image model with close instruction following, sharp text rendering and detailed edits from reference images.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "quality": {
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "type": "string",
      "description": "Sets the price. Default medium"
    },
    "background": {
      "enum": [
        "auto",
        "opaque"
      ],
      "type": "string"
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "3:2",
        "2:3",
        "4:3",
        "3:4",
        "16:9",
        "9:16"
      ],
      "type": "string",
      "description": "Aspect ratio, default 1:1"
    },
    "input_images": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      },
      "maxItems": 6,
      "description": "Reference or source image URLs (https), optional"
    },
    "output_format": {
      "enum": [
        "png",
        "jpeg",
        "webp"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "an infographic of how a toll booth works",
  "quality": "low"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Grok Imagine image generation

POST https://tollnode.com/api/v1/nodes/grok-imagine-image
Price: $0.028 USDC per successful call
Category: Image

xAI's image model: vivid, photorealistic images and edits from a prompt, at a low flat price.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "image": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Optional image to edit (https URL)"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4",
        "3:2",
        "2:3",
        "2:1",
        "1:2"
      ],
      "type": "string",
      "description": "Aspect ratio, default 1:1"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a fox in a reflective vest directing traffic at dawn"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Ideogram 4.5 text-to-image

POST https://tollnode.com/api/v1/nodes/ideogram-4-5
Price: from $0.042 USDC per successful call (by quality: low $0.042, high $0.136, medium $0.082; default medium)
Category: Image

Ideogram's newest model, known for precise typography and layouts. Text-to-image; pick low, medium or high quality.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer",
      "maximum": 2147483647,
      "minimum": 0
    },
    "size": {
      "enum": [
        "1024x1024",
        "1280x896",
        "896x1280",
        "1344x768",
        "768x1344",
        "1536x640",
        "640x1536"
      ],
      "type": "string"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "quality": {
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "type": "string",
      "description": "Sets the price. Default medium"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a vintage poster that says PAY THE TOLL",
  "quality": "low"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Ideogram v3 Turbo

POST https://tollnode.com/api/v1/nodes/ideogram-v3-turbo
Price: $0.042 USDC per successful call
Category: Image

The fastest, cheapest Ideogram v3: stunning realism, creative designs and reliable text in images.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer",
      "maximum": 2147483647,
      "minimum": 0
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "style_type": {
      "enum": [
        "Auto",
        "General",
        "Realistic",
        "Design"
      ],
      "type": "string"
    },
    "aspect_ratio": {
      "enum": [
        "1:3",
        "3:1",
        "1:2",
        "2:1",
        "9:16",
        "16:9",
        "10:16",
        "16:10",
        "2:3",
        "3:2",
        "3:4",
        "4:3",
        "4:5",
        "5:4",
        "1:1"
      ],
      "type": "string",
      "description": "Aspect ratio, default 1:1"
    },
    "magic_prompt": {
      "enum": [
        "Auto",
        "On",
        "Off"
      ],
      "type": "string",
      "description": "Let the model expand your prompt"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a bold logo that reads PAY PER CALL in road-sign style",
  "style_type": "Design"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Instant image editing

POST https://tollnode.com/api/v1/nodes/image-edit-instant
Price: $0.015 USDC per successful call
Category: Image

Edit one or more images with a plain-language instruction in about a second: swap backgrounds, relight, combine subjects.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt",
    "images"
  ],
  "properties": {
    "seed": {
      "type": "integer"
    },
    "images": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      },
      "maxItems": 5,
      "minItems": 1,
      "description": "Images to edit (https URLs)"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "aspect_ratio": {
      "enum": [
        "match_input_image",
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4",
        "3:2",
        "2:3"
      ],
      "type": "string",
      "description": "Aspect ratio, default match_input_image"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "images": [
    "https://tollnode.com/opengraph-image"
  ],
  "prompt": "put this product on a marble kitchen counter"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Instant text-to-image

POST https://tollnode.com/api/v1/nodes/image-instant
Price: $0.008 USDC per successful call
Category: Image

A sharp image from a text prompt in under a second. The cheapest way for an agent to make a picture.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer",
      "description": "Optional seed for repeatable results"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "aspect_ratio": {
      "enum": [
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4",
        "3:2",
        "2:3"
      ],
      "type": "string",
      "description": "Aspect ratio, default 1:1"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a yellow highway warning sign in fog, photo"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Nano Banana 2.1 image generation

POST https://tollnode.com/api/v1/nodes/nano-banana-2-1
Price: from $0.047 USDC per successful call (by resolution: 1K $0.047, 2K $0.070, 4K $0.155; default 1K)
Category: Image

Google's fast image model: crisp text in images, multi-image editing and up to 4K output. Pass reference images to edit.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "resolution": {
      "enum": [
        "1K",
        "2K",
        "4K"
      ],
      "type": "string",
      "description": "Output resolution; sets the price. Default 1K"
    },
    "image_input": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      },
      "maxItems": 8,
      "description": "Reference or source image URLs (https), optional"
    },
    "aspect_ratio": {
      "enum": [
        "match_input_image",
        "1:1",
        "2:3",
        "3:2",
        "3:4",
        "4:3",
        "4:5",
        "5:4",
        "9:16",
        "16:9",
        "21:9"
      ],
      "type": "string",
      "description": "Aspect ratio, default match_input_image"
    },
    "output_format": {
      "enum": [
        "jpg",
        "png"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a road sign that reads TOLLNODE, golden hour",
  "resolution": "1K"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Nano Banana Pro image generation

POST https://tollnode.com/api/v1/nodes/nano-banana-pro
Price: from $0.204 USDC per successful call (by resolution: 1K $0.204, 2K $0.204, 4K $0.406; default 2K)
Category: Image

Google's highest-quality image model: studio-grade detail, accurate text and multi-image composition, at 1K, 2K or 4K.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "resolution": {
      "enum": [
        "1K",
        "2K",
        "4K"
      ],
      "type": "string",
      "description": "Sets the price (1K and 2K cost the same). Default 2K"
    },
    "image_input": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      },
      "maxItems": 8,
      "description": "Reference or source image URLs (https), optional"
    },
    "aspect_ratio": {
      "enum": [
        "match_input_image",
        "1:1",
        "2:3",
        "3:2",
        "3:4",
        "4:3",
        "4:5",
        "5:4",
        "9:16",
        "16:9",
        "21:9"
      ],
      "type": "string",
      "description": "Aspect ratio, default match_input_image"
    },
    "output_format": {
      "enum": [
        "jpg",
        "png"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a product shot of a brass toll token on black velvet",
  "resolution": "2K"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Nano Banana image generation and editing

POST https://tollnode.com/api/v1/nodes/nano-banana
Price: $0.054 USDC per successful call
Category: Image

The original Nano Banana from Google: fast generation and conversational editing that keeps faces and products consistent.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "image_input": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      },
      "maxItems": 8,
      "description": "Reference or source image URLs (https), optional"
    },
    "aspect_ratio": {
      "enum": [
        "match_input_image",
        "1:1",
        "2:3",
        "3:2",
        "3:4",
        "4:3",
        "4:5",
        "5:4",
        "9:16",
        "16:9",
        "21:9"
      ],
      "type": "string",
      "description": "Aspect ratio, default match_input_image"
    },
    "output_format": {
      "enum": [
        "jpg",
        "png"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a cozy reading nook in a converted toll booth, warm light"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Old photo restoration

POST https://tollnode.com/api/v1/nodes/restore-photo
Price: $0.055 USDC per successful call
Category: Image

Repair scratched, faded or damaged photos: removes damage, sharpens and restores natural colour.

Input schema:
```json
{
  "type": "object",
  "required": [
    "image"
  ],
  "properties": {
    "image": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Photo to restore (https URL)"
    },
    "output_format": {
      "enum": [
        "jpg",
        "png"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "image": "https://tollnode.com/examples/restore-photo-before.jpg",
  "output_format": "jpg"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Qwen Image Edit Plus

POST https://tollnode.com/api/v1/nodes/qwen-image-edit-plus
Price: $0.042 USDC per successful call
Category: Image

Multi-image editing from Alibaba's Qwen: combine people, products and scenes, or change text in images precisely.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt",
    "images"
  ],
  "properties": {
    "seed": {
      "type": "integer"
    },
    "images": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      },
      "maxItems": 3,
      "minItems": 1,
      "description": "Images to edit or combine (https URLs)"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "aspect_ratio": {
      "enum": [
        "match_input_image",
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4"
      ],
      "type": "string",
      "description": "Aspect ratio, default match_input_image"
    },
    "output_format": {
      "enum": [
        "webp",
        "jpg",
        "png"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "images": [
    "https://tollnode.com/examples/nano-banana-pro.jpg",
    "https://tollnode.com/examples/restore-photo-after.jpg"
  ],
  "prompt": "put the brass token on the car's dashboard"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Recraft V4 design images

POST https://tollnode.com/api/v1/nodes/recraft-v4
Price: $0.055 USDC per successful call
Category: Image

Image generation with a designer's eye: clean compositions, brand-friendly styles, one flat price.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "size": {
      "enum": [
        "1024x1024",
        "1536x768",
        "768x1536",
        "1280x832",
        "832x1280",
        "1216x896",
        "896x1216",
        "1344x768",
        "768x1344"
      ],
      "type": "string"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "flat illustration of a friendly robot paying a toll"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Seedream 4.5 image generation

POST https://tollnode.com/api/v1/nodes/seedream-4-5
Price: $0.055 USDC per successful call
Category: Image

ByteDance's upgraded image model with stronger spatial understanding and world knowledge, at 2K or 4K for one price.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "size": {
      "enum": [
        "2K",
        "4K"
      ],
      "type": "string",
      "description": "Same price for both. Default 2K"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "image_input": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      },
      "maxItems": 6,
      "description": "Reference or source image URLs (https), optional"
    },
    "aspect_ratio": {
      "enum": [
        "match_input_image",
        "1:1",
        "4:3",
        "3:4",
        "4:5",
        "5:4",
        "16:9",
        "9:16",
        "3:2",
        "2:3",
        "21:9",
        "9:21"
      ],
      "type": "string",
      "description": "Aspect ratio, default match_input_image"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a detailed cutaway illustration of a futuristic toll station"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Seedream 5 Lite image generation

POST https://tollnode.com/api/v1/nodes/seedream-5-lite
Price: $0.049 USDC per successful call
Category: Image

ByteDance's image model with built-in reasoning and example-based editing, at 2K or 3K, one flat price.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "size": {
      "enum": [
        "2K",
        "3K"
      ],
      "type": "string",
      "description": "Same price for both. Default 2K"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "image_input": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      },
      "maxItems": 6,
      "description": "Reference or source image URLs (https), optional"
    },
    "aspect_ratio": {
      "enum": [
        "match_input_image",
        "1:1",
        "4:3",
        "3:4",
        "16:9",
        "9:16",
        "3:2",
        "2:3",
        "21:9"
      ],
      "type": "string",
      "description": "Aspect ratio, default match_input_image"
    },
    "output_format": {
      "enum": [
        "png",
        "jpeg"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "isometric city of toll booths, clean vector style"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## Z-Image Turbo fast images

POST https://tollnode.com/api/v1/nodes/z-image-turbo
Price: $0.008 USDC per successful call
Category: Image

A super-fast 6B text-to-image model with excellent photorealism and text, at 1 megapixel for a fraction of a cent.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "negative_prompt": {
      "type": "string",
      "maxLength": 1000
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "street photo of a rainy neon toll plaza, reflections"
}
```

Example response:
```json
{
  "images": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ]
}
```

## VIN decoder

POST https://tollnode.com/api/v1/nodes/vin-decode
Price: $0.005 USDC per successful call
Category: Lookup

Validate a 17-character VIN and return make, model, year, plant and body details plus an ISO 3779 breakdown.

Input schema:
```json
{
  "type": "object",
  "required": [
    "vin"
  ],
  "properties": {
    "vin": {
      "type": "string",
      "maxLength": 17,
      "minLength": 17,
      "description": "17-character VIN"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "vin": "1HGCM82633A004352"
}
```

Example response:
```json
{
  "vin": "1HGCM82633A004352",
  "local": {
    "vds": "CM826",
    "wmi": "1HG",
    "country": "United States",
    "plantCode": "A",
    "checkDigit": "3",
    "countryCode": "US",
    "manufacturer": "Honda",
    "sequentialNumber": "004352"
  },
  "nhtsa": {
    "make": "HONDA",
    "model": "Accord",
    "bodyClass": "Coupe",
    "errorCode": "0",
    "errorText": "0 - VIN decoded clean. Check Digit (9th position) is correct",
    "modelYear": "2003",
    "vehicleType": "PASSENGER CAR",
    "plantCountry": "UNITED STATES (USA)"
  },
  "cached": false,
  "validation": {
    "valid": true
  }
}
```

## Google web search results

POST https://tollnode.com/api/v1/nodes/web-search
Price: $0.008 USDC per successful call
Category: Search

Run one Google search and get the first page of organic results as JSON: title, URL, description and position, plus related queries.

Input schema:
```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "pattern": "^[^\\n\\r]+$",
      "maxLength": 300,
      "minLength": 1,
      "description": "One search query (single line)"
    },
    "countryCode": {
      "type": "string",
      "pattern": "^[a-z]{2}$",
      "description": "Optional two-letter country code, lowercase, e.g. us, gb, de"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "query": "best x402 api marketplace"
}
```

Example response:
```json
{
  "results": [
    {
      "url": "http://www.google.com/search?q=x402+payments&gl=us",
      "hasNextPage": true,
      "searchQuery": {
        "page": 1,
        "term": "x402 payments",
        "countryCode": "US",
        "resultsPerPage": 10
      },
      "peopleAlsoAsk": [
        {
          "answer": "An open payment standard built on HTTP 402.",
          "question": "What is x402?"
        }
      ],
      "organicResults": [
        {
          "url": "https://www.x402.org/",
          "title": "x402 – An open payment standard",
          "position": 1,
          "description": "x402 lets any HTTP endpoint charge per request in stablecoins."
        }
      ],
      "relatedQueries": [
        {
          "url": "https://www.google.com/search?q=x402+payments+github",
          "title": "x402 payments github"
        }
      ]
    }
  ]
}
```

## P-Video text-to-video

POST https://tollnode.com/api/v1/nodes/video-p-video
Price: from $0.136 USDC per successful call (by resolution: 720p $0.136, 1080p $0.271; default 720p)
Category: Video

Fast 5-second videos with sound from a text prompt or a starting image, at 720p or 1080p.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer"
    },
    "image": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Optional starting image (https URL)"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "resolution": {
      "enum": [
        "720p",
        "1080p"
      ],
      "type": "string",
      "description": "Sets the price. Default 720p"
    },
    "aspect_ratio": {
      "enum": [
        "16:9",
        "9:16",
        "4:3",
        "3:4",
        "3:2",
        "2:3",
        "1:1"
      ],
      "type": "string",
      "description": "Aspect ratio, default 16:9"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a drone shot gliding over a desert highway at sunset",
  "resolution": "720p"
}
```

Example response:
```json
{
  "videos": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ],
  "aiGenerated": true
}
```

## Seedance 1 Lite text-to-video

POST https://tollnode.com/api/v1/nodes/video-seedance-1-lite
Price: from $0.123 USDC per successful call (by resolution: 480p $0.123, 720p $0.244; default 480p)
Category: Video

ByteDance's Seedance Lite: 5-second videos from text or an image, with cinematic camera moves, at 480p or 720p.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer"
    },
    "image": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Optional starting image (https URL)"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "resolution": {
      "enum": [
        "480p",
        "720p"
      ],
      "type": "string",
      "description": "Sets the price. Default 480p"
    },
    "aspect_ratio": {
      "enum": [
        "16:9",
        "4:3",
        "1:1",
        "3:4",
        "9:16",
        "21:9",
        "9:21"
      ],
      "type": "string",
      "description": "Aspect ratio, default 16:9"
    },
    "camera_fixed": {
      "type": "boolean",
      "description": "Keep the camera still"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "prompt": "a vintage car driving through a toll gate at night, neon reflections, cinematic",
  "resolution": "480p"
}
```

Example response:
```json
{
  "videos": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ],
  "aiGenerated": true
}
```

## Wan 2.2 image-to-video

POST https://tollnode.com/api/v1/nodes/video-wan-2-2
Price: from $0.069 USDC per successful call (by resolution: 480p $0.069, 720p $0.150; default 480p)
Category: Video

Animate a still image into a 5-second video clip with Wan 2.2: fast and cheap, at 480p or 720p.

Input schema:
```json
{
  "type": "object",
  "required": [
    "prompt",
    "image"
  ],
  "properties": {
    "seed": {
      "type": "integer"
    },
    "image": {
      "type": "string",
      "format": "uri",
      "pattern": "^https://",
      "description": "Starting image (https URL)"
    },
    "prompt": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "What to create or change"
    },
    "resolution": {
      "enum": [
        "480p",
        "720p"
      ],
      "type": "string",
      "description": "Sets the price. Default 480p"
    }
  },
  "additionalProperties": false
}
```

Example request body:
```json
{
  "image": "https://tollnode.com/examples/restore-photo-after.jpg",
  "prompt": "the car pulls away from the toll booth, gentle camera pan",
  "resolution": "480p"
}
```

Example response:
```json
{
  "videos": [
    "https://tollnode.com/api/v1/files/00000000-0000-0000-0000-000000000000/0"
  ],
  "aiGenerated": true
}
```