Credit-Based API Documentation

Generate images using prepaid credits with API key authentication. Great for production, teams, and predictable billing.

Buy credits Try the playground

Authentication

All credit-based API endpoints require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key by purchasing credits.

Endpoints

GET /credits/balance POST /image/generate GET /image/status GET /image/all

GET /credits/balance

Check your current credit balance.

curl -X GET \
  'https://imference.com/credits/balance' \
  -H 'Authorization: Bearer YOUR_API_KEY'

import requests

url = "https://imference.com/credits/balance"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(url, headers=headers)
print(response.json())  # {"credits": 100}

fetch("https://imference.com/credits/balance", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
})
  .then(res => res.json())
  .then(data => console.log("Credits:", data.credits))
  .catch(console.error);

Response:

{"credits": 100}

POST /image/generate

Generate an image using 5 credits. Returns a request_id for status polling.

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

import requests

url = "https://imference.com/image/generate"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "model": "illustrious-hassuka-xl",
    "prompt": "A cat astronaut floating in space"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())  # {"request_id": "abc123..."}

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

fetch("https://imference.com/image/generate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "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

Response:

{"request_id": "abc123..."}

GET /image/status

Check the status of an image generation request.

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

import requests

request_id = "YOUR_REQUEST_ID"
url = f"https://imference.com/image/status?request_id={request_id}"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

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

const requestId = "YOUR_REQUEST_ID";

fetch(`https://imference.com/image/status?request_id=${requestId}`, {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
})
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(console.error);

Response (when ready):

{
  "data": {
    "RequestID": "abc123...",
    "URL": "https://blob.imference.com/large/uuid.webp",
    "Format": "webp",
    "Seed": 12345,
    "Timestamp": "2024-01-15T10:30:00Z"
  }
}

GET /image/all

Get all images generated with your API key.

curl -X GET \
  'https://imference.com/image/all' \
  -H 'Authorization: Bearer YOUR_API_KEY'

fetch("https://imference.com/image/all", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
})
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(console.error);

Rate Limits

50 requests per minute per API key.

If you exceed this limit, you'll receive a 429 Too Many Requests response.

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)
401	Unauthorized	Missing or invalid API key
402	Payment Required	Insufficient credits for the requested generation
404	Not Found	Invalid endpoint or request_id not found
429	Too Many Requests	Rate limit exceeded (50 req/min)
500	Internal Server Error	Server-side error — retry or contact support

Example error response:

{"error": "insufficient credits"}