O OpenMOSSTutorial

How to Use MOSS Image API

A step-by-step MOSS Image API tutorial with Node.js, Python and cURL: submit a text to image job, poll it or receive a webhook, and download the image. The example below costs $0.039.

Endpoints: 1; Text to Image
Example request: $0.039; Text to Image
Languages: 3; Node.js · Python · cURL
Failed runs: $0; refunded automatically

Get API key Create with MOSS Image API docs

Get an API key

Create an account, add credits and create a key in Dashboard → API keys. Store it as CHEAPERGEN_API_KEY on your server. Every request sends it as a bearer token.

How to get a MOSS Image API key

Choose a MOSS Image endpoint

Each task has its own endpoint. All of them take a JSON body and return a generation you can poll.

MOSS Image API endpoints, required inputs and prices
Task	Endpoint	Required	From
Text to Image	openmoss/moss-image/text-to-image	prompt	$0.0384/image

Submit a text to image job

This program submits the job, polls every 3 seconds until it finishes and prints the image URL. Swap the prompt and settings for your own.

const API = "https://cheapergen.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.CHEAPERGEN_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Submit the job
let job = await fetch(`${API}/run/openmoss/moss-image/text-to-image`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": "A hand-painted wooden sign outside a tea shop that reads “山间茶舍 MOUNTAIN TEA HOUSE — OPEN DAILY 9–6”, morning mist, warm light",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }),
}).then((r) => r.json());

// 2. Poll until it finishes (or pass webhook_url and skip polling)
while (job.status === "queued" || job.status === "running") {
  await new Promise((r) => setTimeout(r, 3000));
  job = await fetch(`${API}/generations/${job.id}`, { headers }).then((r) => r.json());
}

console.log(job.status === "succeeded" ? job.output.images[0].url : job.error);

import os, time, requests

API = "https://cheapergen.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['CHEAPERGEN_API_KEY']}"}

# 1. Submit the job
job = requests.post(f"{API}/run/openmoss/moss-image/text-to-image", headers=headers, json={
    "prompt": "A hand-painted wooden sign outside a tea shop that reads “山间茶舍 MOUNTAIN TEA HOUSE — OPEN DAILY 9–6”, morning mist, warm light",
    "aspect_ratio": "1:1",
    "resolution": "1K"
}).json()

# 2. Poll until it finishes (or pass "webhook_url" and skip polling)
while job["status"] in ("queued", "running"):
    time.sleep(3)
    job = requests.get(f"{API}/generations/{job['id']}", headers=headers).json()

print(job["status"], job["output"]["images"][0]["url"] if job["status"] == "succeeded" else job["error"])

curl -X POST https://cheapergen.com/api/v1/run/openmoss/moss-image/text-to-image \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "A hand-painted wooden sign outside a tea shop that reads “山间茶舍 MOUNTAIN TEA HOUSE — OPEN DAILY 9–6”, morning mist, warm light",
  "aspect_ratio": "1:1",
  "resolution": "1K"
}'

Set the parameters that matter

The settings for openmoss/moss-image/text-to-image, with what each one does to the price.

MOSS Image Text to Image parameters and their effect on price
Parameter	Type · default	What it does	Price effect
aspect_ratio	string (enum) · 1:1	Output image shape. At 1K: 1:1 = 1024 × 1024, 4:5 = 912 × 1136, 5:4 = 1136 × 912, 3:4 = 880 × 1168, 4:3 = 1168 × 880, 2:3 = 832 × 1248, 3:2 = 1248 × 832, 9:16 = 768 × 1360, 16:9 = 1360 × 768, 1:2 = 720 × 1440, 2:1 = 1440 × 720, 9:21 = 656 × 1552, 21:9 = 1552 × 656, 1:3 = 576 × 1760, 3:1 = 1760 × 576. 1:1 · 4:5 · 5:4 · 3:4 · 4:3 · 2:3 · 3:2 · 9:16 · 16:9 · 1:2 · 2:1 · 9:21 · 21:9 · 1:3 · 3:1	1:1: $0.0384/image
resolution	string (enum) · 1K	Output size, the same price at every aspect ratio: 1K = 1 MP (1024 × 1024), 1.5K ≈ 2.25 MP (1536 × 1536), 2K = 4 MP (2048 × 2048) at 1:1, with 1 MP = 1024² px. Other ratios keep the pixels: each side is the 1:1 side × √ratio, rounded down to a multiple of 16 (e.g. 2K 16:9 = 2720 × 1536). 1K · 1.5K · 2K	1K: $0.0384/image 1.5K: $0.0826/image 2K: $0.1534/image
seed	integer	Use the same seed and settings to reproduce a result. Leave empty for random.	None
enable_safety_checker	boolean · true	If set to true, the safety checker will be enabled. Content our Acceptable Use Policy prohibits stays blocked either way.	None

Get the result

A job moves from queued to running to succeeded, failed or canceled. Poll GET /api/v1/generations/{id}, or pass webhook_url and we POST the result to you. Download the output and store it yourself.

200 — succeeded

{
  "id": "gen_8c2QmX1nq0k4",
  "object": "generation",
  "model": "openmoss/moss-image",
  "endpoint": "openmoss/moss-image/text-to-image",
  "mode": "text-to-image",
  "status": "succeeded",
  "input": {
    "prompt": "A hand-painted wooden sign outside a tea shop that reads “山间茶舍 MOUNTAIN TEA HOUSE — OPEN DAILY 9–6”, morning mist, warm light",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  },
  "output": {
    "images": [
      {
        "url": "https://cdn.cheapergen.com/outputs/gen_8c2Q-0.png",
        "content_type": "image/png",
        "width": 2048,
        "height": 2048
      }
    ]
  },
  "error": null,
  "cost": {
    "amount_usd": 0.2255,
    "currency": "usd",
    "estimated": false,
    "official_usd": 0.264,
    "list_price_source": "reference",
    "list_price_label": "fal API",
    "saved_usd": 0.0385
  },
  "source": "api",
  "created_at": "2026-10-15T09:21:04Z",
  "started_at": "2026-10-15T09:21:06Z",
  "completed_at": "2026-10-15T09:22:31Z"
}

Verify webhook signatures

Price a request before you run it

The quote endpoint is free and needs no key. It returns the price, the fal API price and your discount for exactly the input you send.

curl -X POST https://cheapergen.com/api/v1/quote/openmoss/moss-image/text-to-image \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A hand-painted wooden sign outside a tea shop that reads “山间茶舍 MOUNTAIN TEA HOUSE — OPEN DAILY 9–6”, morning mist, warm light","aspect_ratio":"1:1","resolution":"1K"}'

API errors and what to do
Status	Code	Meaning
400	invalid_request	A parameter is missing or out of range — the message names it.
401	unauthorized	Missing, malformed or revoked API key.
402	insufficient_balance	Not enough credits for the quoted price; top up or enable auto top-up.
429	rate_limited	Too many requests or generations in progress; back off and retry.
502	upstream_error	The model provider failed; the hold is refunded and you can retry.
503	model_unavailable	No healthy route right now; retry later or pick another model.

Full MOSS Image API documentation

FAQ

MOSS Image API questions

No. The API is plain HTTPS with JSON, so the Node.js (fetch) and Python (requests) examples on this page are complete programs. Any language that can send an HTTP request works.

Yes. Add "webhook_url" to the request body and we POST the finished generation to it, signed with a CheaperGen-Signature header (HMAC-SHA256 of the timestamp and raw body). Polling GET /api/v1/generations/{id} works too.

Text to Image starts at $0.0384/image; the example request on this page costs $0.039, 23% below the fal API price. Failed generations are refunded automatically.