API Reference

Quickstart — Credits

1. Buy credits — your API key is created with the first purchase.
2. POST /generate with your model + prompt (Bearer auth).
3. Poll GET /status?request_id=… until it returns your media URL.

curl -X POST 'https://imference.com/generate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model": "illustrious-hassuka-xl", "prompt": "A cat astronaut floating in space"}'
# → {"request_id": "abc-123", "kind": "image"}

curl 'https://imference.com/status?request_id=abc-123' \
  -H 'Authorization: Bearer YOUR_API_KEY'
# 404 while running · 422 if failed · 200 with the media URL when done

import requests, time

BASE = "https://imference.com"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

r = requests.post(f"{BASE}/generate", headers=headers, json={
    "model": "illustrious-hassuka-xl",
    "prompt": "A cat astronaut floating in space",
})
request_id = r.json()["request_id"]

while True:
    s = requests.get(f"{BASE}/status", headers=headers, params={"request_id": request_id})
    if s.status_code == 200:
        print(s.json()["data"]["URL"]); break
    if s.status_code == 422:
        raise RuntimeError(s.json()["error"])   # generation failed — stop polling
    time.sleep(1)                                # 404 → still running

Quickstart — x402

No account, no key: your wallet pays per call in USDC on Base. The first request answers 402 Payment Required with the price; your x402 client signs an EIP-3009 authorization and retries automatically. Use an x402 client library or try the playground.

import { wrapFetchWithPayment } from "x402-fetch";

const fetchWithPay = wrapFetchWithPayment(fetch, walletClient); // your viem wallet
const res = await fetchWithPay("https://imference.com/ondemand/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ model: "illustrious-hassuka-xl", prompt: "A cat astronaut" }),
});
const { request_id } = await res.json();
// then poll GET /ondemand/status?request_id=… (no auth needed)

Authentication & payment

Generate an image or a video — one endpoint for every model. The media kind and the price come from the model; the response echoes both. Returns a request_id for status polling.

curl -X POST 'https://imference.com/generate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "illustrious-hassuka-xl",
    "prompt": "A cat astronaut floating in space",
    "width": 1024, "height": 1024,
    "steps": 28, "guidance_scale": 6
  }'

import requests

r = requests.post(
    "https://imference.com/generate",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"model": "illustrious-hassuka-xl",
          "prompt": "A cat astronaut floating in space"},
)
print(r.json())  # {"request_id": "abc-123", "kind": "image"}

const res = await fetch("https://imference.com/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "illustrious-hassuka-xl",
    prompt: "A cat astronaut floating in space",
  }),
});
const { request_id, kind } = await res.json();

# A bare request returns 402 with the payment requirements (price in USDC).
# Use an x402 client to sign the X-PAYMENT header automatically:
curl -X POST 'https://imference.com/ondemand/generate' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "illustrious-hassuka-xl",
    "prompt": "A cat astronaut floating in space"
  }'

import { wrapFetchWithPayment } from "x402-fetch";

const fetchWithPay = wrapFetchWithPayment(fetch, walletClient);
const res = await fetchWithPay("https://imference.com/ondemand/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "illustrious-hassuka-xl",
    prompt: "A cat astronaut floating in space",
  }),
});
const { request_id, kind } = await res.json();

{"request_id": "abc-123", "kind": "image"}

Video generation

Same endpoint — pick a video model and it generates a video. No img_url → text-to-video; with img_url → image-to-video. The price adjusts to the model automatically.

curl -X POST 'https://imference.com/generate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "wan22-video",
    "prompt": "A fox running through a snowy forest",
    "num_frames": 81, "fps": 20
  }'
# → {"request_id": "…", "kind": "video"}  — poll /status; expect minutes, not seconds

Check a generation. The polling contract is explicit:

curl 'https://imference.com/status?request_id=YOUR_REQUEST_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl 'https://imference.com/ondemand/status?request_id=YOUR_REQUEST_ID'
# no auth needed — the request_id is the capability

{
  "data": {
    "RequestID": "abc-123",
    "Kind": "image",
    "URL": "https://blob.imference.com/large/uuid.webp",
    "Format": "webp",
    "Seed": 12345,
    "Timestamp": "2026-07-30T10:30:00Z"
  }
}

All media (images and videos) generated with your API key, newest first. Each row carries a Kind field.

curl 'https://imference.com/media/all' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Your remaining credit balance.

curl 'https://imference.com/credits/balance' \
  -H 'Authorization: Bearer YOUR_API_KEY'
# → {"credits": 1250}

Prepay API-key credits with one on-chain USDC payment — the x402 price is exactly credits × $0.001. Saves the per-call network fee when you generate a lot. Min 100, max 1,000,000 credits per call. An empty api_key creates a fresh key and returns it. Or use the pricing page UI.

const res = await fetchWithPay("https://imference.com/ondemand/credits/add", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ credits: 5000, api_key: "" }), // "" → new key
});
// → {"api_key": "…", "credits_added": 5000}

Models & formats

Public, no auth. GET /api/models lists every model with its defaults (steps, CFG, prompts) and its cost — im_cost in credits (1 credit = $0.001; the x402 price is the same amount in USDC). GET /api/formats lists each model's supported resolutions and ratios, so you never hardcode sizes.

curl 'https://imference.com/api/models'
curl 'https://imference.com/api/formats'

Errors

Standard HTTP codes; error bodies are {"error": "…"}.

Rate limits & terms

50 requests per minute per API key (credits) or wallet address (x402). Exceeding it returns 429.

See the Terms of Service.