x402 API Documentation

Pay-per-use image and video generation with on-chain USDC payments. No accounts, no API keys required.

Try the playground x402 quick start guide

Endpoints

POST /ondemand/image/generate POST /ondemand/video/generate GET /ondemand/status

POST /ondemand/image/generate

Generate an image with on-chain USDC payment. Requires x402 payment header.

curl -X POST \
  'https://imference.com/ondemand/image/generate' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "illustrious-hassuka-xl",
    "prompt": "A cat astronaut floating in space",
    "wallet_address": "0x123..."
  }'

import requests

url = "https://imference.com/ondemand/image/generate"
headers = {"Content-Type": "application/json"}
json_data = {
    "model": "illustrious-hassuka-xl",
    "prompt": "A cat astronaut floating in space",
    "wallet_address": "0x123..."
}

response = requests.post(url, headers=headers, json=json_data)
print(response.status_code, response.json())

const payload = {
  model: "illustrious-hassuka-xl",
  prompt: "A cat astronaut floating in space",
  wallet_address: "0x123..."
};

fetch("https://imference.com/ondemand/image/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload)
})
  .then(res => res.json())
  .then(data => console.log("request_id:", data.request_id))
  .catch(console.error);

Request Body:

model (required) - Model code (e.g., "illustrious-hassuka-xl")
prompt (required) - Text description of the image
wallet_address (required) - Your Ethereum wallet address
width (optional) - Image width in pixels (default: 1024)
height (optional) - Image height in pixels (default: 1024)
negative_prompt (optional) - What to avoid in generation

POST /ondemand/video/generate

Generate a video with on-chain USDC payment. Supports Veo models.

curl -X POST \
  'https://imference.com/ondemand/video/generate' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "A bird flying over a forest",
    "wallet_address": "0x123...",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration_seconds": 8
  }'

const payload = {
  model: "veo-3.1-generate-preview",
  prompt: "A bird flying over a forest",
  wallet_address: "0x123...",
  aspect_ratio: "16:9",
  resolution: "1080p",
  duration_seconds: 8
};

fetch("https://imference.com/ondemand/video/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload)
})
  .then(res => res.json())
  .then(data => console.log("request_id:", data.request_id))
  .catch(console.error);

GET /ondemand/status

Check the status of your image or video generation request.

curl -X GET \
  'https://imference.com/ondemand/status?request_id=YOUR_REQUEST_ID'

import requests

request_id = "YOUR_REQUEST_ID"
url = f"https://imference.com/ondemand/status?request_id={request_id}"

response = requests.get(url)
print(response.status_code, response.json())

const requestId = "YOUR_REQUEST_ID";

fetch(`https://imference.com/ondemand/status?request_id=${requestId}`)
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(console.error);

Response:

type - "image" or "video"
data.URL - URL to download the generated media
data.Seed - Random seed used for generation
data.Timestamp - When the media was generated

Error Responses

The API returns standard HTTP status codes. Error responses include a JSON body with an error field.

Status	Meaning	Common Cause
400	Bad Request	Missing or invalid fields (e.g. no prompt, unknown model)
402	Payment Required	No valid on-chain payment detected for your wallet
404	Not Found	Invalid endpoint or request_id not found
500	Internal Server Error	Server-side error — retry or contact support

Example error response:

{"error": "payment required"}