From d611e6b82ec67e64737d51e443a96c220b4275a5 Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Sun, 26 Jul 2026 13:58:23 +0300
Subject: [PATCH 1/3] docs: add image generation and edit job pages

Document the image.generate and image.edit jobs plus a Generation API concept page. Covers params, the tier/pinned-model catalog from gen-models.json, per-model controls, GET /models discovery, and the webp output shape. Adds the pages to docs.json nav (Generate subgroup under Jobs, Generation under Concepts).
---
 concepts/generation.mdx | 106 +++++++++++++++
 docs.json               |   9 ++
 jobs/image-edit.mdx     | 257 ++++++++++++++++++++++++++++++++++++
 jobs/image-generate.mdx | 280 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 652 insertions(+)
 create mode 100644 concepts/generation.mdx
 create mode 100644 jobs/image-edit.mdx
 create mode 100644 jobs/image-generate.mdx

diff --git a/concepts/generation.mdx b/concepts/generation.mdx
new file mode 100644
index 0000000..c642cf0
--- /dev/null
+++ b/concepts/generation.mdx
@@ -0,0 +1,106 @@
+---
+title: "The Generation API"
+sidebarTitle: "Generation"
+description: "Generate images from a text prompt or edit them from an instruction on hosted diffusion models. One async API, one job shape, many models."
+icon: "sparkles"
+keywords: ["generation api", "ai media generation api", "text to image api", "image editing api", "diffusion model api", "hosted diffusion models", "ai image api", "generative media api"]
+canonical: "https://rendobar.com/docs/concepts/generation"
+---
+
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/concepts/generation/#article",
+      "headline": "The Generation API",
+      "description": "Generate images from a text prompt or edit them from an instruction on hosted diffusion models. One async API, one job shape, many models.",
+      "datePublished": "2026-07-26",
+      "dateModified": "2026-07-26",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
+Rendobar's Generation API creates new media from a prompt on hosted diffusion models. It is one of the platform's products, and it submits, runs, and returns like every other job. You describe what you want, the job runs on a GPU, and the result comes back as a signed file URL.
+
+## Modalities
+
+Images are the first modality. You can generate an image from a text prompt, or edit existing images from a written instruction.
+
+<CardGroup cols={2}>
+  <Card title="Image generate" icon="image" href="/jobs/image-generate">
+    Turn a text prompt into a webp image. Pick a tier or pin an exact model.
+  </Card>
+  <Card title="Image edit" icon="wand-magic-sparkles" href="/jobs/image-edit">
+    Edit one to four reference images from a plain-language instruction.
+  </Card>
+</CardGroup>
+
+More modalities will join the same surface over time. Only image generation and editing are available today.
+
+## Tiers or exact models
+
+Every generation job takes a `model`. You can name a tier and let the platform choose, or pin an exact model id.
+
+- **Tiers** (`economy`, `standard`, `premium`) express a price and quality posture without naming a model. Omit `model` and you get `economy`.
+- **Exact ids** (for example `qwen-image-2512`) pin the model and unlock its own controls, such as denoise steps, guidance, and a negative prompt.
+
+Tier aliases can be re-pointed to newer models as the catalog grows. Pin an exact id when you need a result to stay stable across that change.
+
+## Discover models
+
+`GET /models` returns the live catalog: every model with its supported jobs, tier, capabilities, step range, and an estimated per-image cost. Filter to one job type with `?job=`. Build a model picker against this endpoint instead of hardcoding the list.
+
+```bash
+curl "https://api.rendobar.com/models" \
+  -H "Authorization: Bearer rb_YOUR_KEY"
+```
+
+```json
+{
+  "data": [
+    {
+      "id": "qwen-image-2512",
+      "jobs": ["image.generate"],
+      "tier": "premium",
+      "estCostUsd": 0.0394,
+      "maxRefImages": 0,
+      "steps": { "default": 50, "min": 20, "max": 50 },
+      "supports": { "negativePrompt": true, "guidance": true },
+      "enhanceDefault": true,
+      "status": "active"
+    }
+  ]
+}
+```
+
+The `estCostUsd` field is an estimate to help you compare models, not a fixed price. Jobs bill on the compute they use, cost-plus. See [credits and billing](/concepts/credits).
+
+## Same job, same shape
+
+A generation job is a [job](/concepts/job) like any other. You submit it to `POST /jobs`, it runs async, and you poll, [wait](/sdk#wait), or receive a [webhook](/guides/webhooks). The image jobs return a single webp file in `output.file`, with `output.data` set to `null`.
+
+```ts
+import { createClient, outputUrl } from "@rendobar/sdk";
+
+const client = createClient({ apiKey: "rb_YOUR_KEY" });
+
+const job = await client.jobs.run({
+  type: "image.generate",
+  params: { prompt: "A paper boat on a still pond at dawn", model: "standard" },
+});
+
+console.log(outputUrl(job)); // signed URL to the webp
+```
+
+## See also
+
+- [Image generate](/jobs/image-generate): text to image, with the full model catalog
+- [Image edit](/jobs/image-edit): instruction editing with one to four reference images
+- [How a job works](/concepts/job): statuses and the output shape
+- [SDK](/sdk): `jobs.run`, `jobs.wait`, and reading the output
+- [Credits and billing](/concepts/credits): how compute-based billing works
diff --git a/docs.json b/docs.json
index ede5e85..e839d3a 100644
--- a/docs.json
+++ b/docs.json
@@ -34,6 +34,7 @@
             "group": "Concepts",
             "pages": [
               "concepts/job",
+              "concepts/generation",
               "guides/webhooks",
               "guides/callbacks"
             ]
@@ -52,6 +53,14 @@
                   "jobs/captions/animate",
                   "jobs/captions/burn"
                 ]
+              },
+              {
+                "group": "Generate",
+                "icon": "sparkles",
+                "pages": [
+                  "jobs/image-generate",
+                  "jobs/image-edit"
+                ]
               }
             ]
           },
diff --git a/jobs/image-edit.mdx b/jobs/image-edit.mdx
new file mode 100644
index 0000000..27e21e9
--- /dev/null
+++ b/jobs/image-edit.mdx
@@ -0,0 +1,257 @@
+---
+title: "Edit an image with an instruction"
+sidebarTitle: "Image edit"
+description: "Use a written instruction to edit one to four reference images on hosted diffusion models. Swap a background, restyle, or compose."
+icon: "wand-magic-sparkles"
+keywords: ["image editing api", "instruction image edit api", "ai image edit api", "qwen image edit api", "flux kontext api", "background swap api", "restyle image api", "reference image edit", "compose images api"]
+canonical: "https://rendobar.com/docs/jobs/image-edit"
+---
+
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/jobs/image-edit/#article",
+      "headline": "Edit an image with an instruction",
+      "description": "Use a written instruction to edit one to four reference images on hosted diffusion models. Swap a background, restyle, or compose.",
+      "datePublished": "2026-07-26",
+      "dateModified": "2026-07-26",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
+`image.edit` takes one to four reference images and a written instruction, then produces a new image on a hosted diffusion model. No masks and no coordinates. You describe the change in plain language and the model applies it. The result is a webp file returned as a signed URL.
+
+This is one product in [Rendobar's Generation API](/concepts/generation).
+
+## Edit an image
+
+Reference images go in `inputs.images` as an array of URLs. The instruction goes in `params.prompt`.
+
+<CodeGroup>
+
+```ts SDK
+import { createClient, outputUrl } from "@rendobar/sdk";
+
+const client = createClient({ apiKey: "rb_YOUR_KEY" });
+
+const job = await client.jobs.run({
+  type: "image.edit",
+  inputs: { images: ["https://cdn.rendobar.com/assets/examples/photo.jpg"] },
+  params: {
+    prompt: "Place the product on a pale grey studio backdrop with a soft shadow underneath",
+  },
+});
+
+console.log(outputUrl(job)); // signed URL to the edited webp
+```
+
+```bash cURL
+curl -X POST "https://api.rendobar.com/jobs" \
+  -H "Authorization: Bearer rb_YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "image.edit",
+    "inputs": { "images": ["https://cdn.rendobar.com/assets/examples/photo.jpg"] },
+    "params": { "prompt": "Place the product on a pale grey studio backdrop with a soft shadow underneath" }
+  }'
+# Returns { "data": { "id": "job_...", "status": "waiting" } }.
+# Poll GET /jobs/{id} until "status": "complete".
+```
+
+```python Python
+import requests, time
+
+base = "https://api.rendobar.com"
+headers = {"Authorization": "Bearer rb_YOUR_KEY"}
+
+job = requests.post(
+    f"{base}/jobs",
+    headers=headers,
+    json={
+        "type": "image.edit",
+        "inputs": {"images": ["https://cdn.rendobar.com/assets/examples/photo.jpg"]},
+        "params": {"prompt": "Place the product on a pale grey studio backdrop with a soft shadow underneath"},
+    },
+).json()["data"]
+
+while job["status"] not in ("complete", "failed", "cancelled"):
+    time.sleep(1)
+    job = requests.get(f"{base}/jobs/{job['id']}", headers=headers).json()["data"]
+
+print(job["output"]["file"]["url"])  # the edited webp
+```
+
+</CodeGroup>
+
+Each URL can be a public link or an [uploaded asset's](/sdk#uploads) content URL. The output size follows the first reference image unless you set `width` and `height`.
+
+## Reference images
+
+`inputs.images` accepts one to four URLs. The per-model cap is tighter than the schema ceiling, so a request that clears the schema can still be rejected against the resolved model.
+
+| Model | Reference images |
+|---|---|
+| `flux-2-klein-4b` (economy) | Up to 4 |
+| `qwen-image-edit-2511-lightning` (standard) | Up to 3 |
+| `qwen-image-edit-2511` (premium) | Up to 3 |
+
+Passing more images than the resolved model accepts returns `VALIDATION_ERROR` before anything is billed. Multiple references let you compose a scene, for example a product from one image on a background from another.
+
+## Tiers and models
+
+Set `model` to a tier alias or pin an exact model id. Omit it and you get the `economy` tier. Aliases can be re-pointed as the catalog grows, so pin an exact id when you need a result to stay stable.
+
+| Tier | Model | Est. USD per image | Reference images | Controls |
+|---|---|---|---|---|
+| `economy` (default) | `flux-2-klein-4b` | 0.0009 | Up to 4 | prompt only |
+| `standard` | `qwen-image-edit-2511-lightning` | 0.0024 | Up to 3 | steps (4 to 8) |
+| `premium` | `qwen-image-edit-2511` | 0.033 | Up to 3 | steps (20 to 40), guidance, negative prompt |
+
+<Info>
+The USD figures are per-image cost estimates, the same values [`GET /models`](#discover-models) returns. They are estimates, not a fixed price. Jobs bill on the compute they use, cost-plus. See [credits and billing](/concepts/credits).
+</Info>
+
+## Model-specific controls
+
+Tier aliases accept the base fields only. To use `steps`, `guidance`, or `negativePrompt`, pin an exact model id. Only `qwen-image-edit-2511` accepts `guidance` and `negativePrompt`. `flux-2-klein-4b` fixes its own step count and exposes the base fields only.
+
+<CodeGroup>
+
+```ts SDK
+await client.jobs.run({
+  type: "image.edit",
+  inputs: { images: ["https://cdn.rendobar.com/assets/examples/photo.jpg"] },
+  params: {
+    prompt: "Turn the daytime sky into a clear starry night",
+    model: "qwen-image-edit-2511",
+    steps: 30,
+    guidance: 4,
+    negativePrompt: "artifacts, halos",
+  },
+});
+```
+
+```bash cURL
+curl -X POST "https://api.rendobar.com/jobs" \
+  -H "Authorization: Bearer rb_YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "image.edit",
+    "inputs": { "images": ["https://cdn.rendobar.com/assets/examples/photo.jpg"] },
+    "params": {
+      "prompt": "Turn the daytime sky into a clear starry night",
+      "model": "qwen-image-edit-2511",
+      "steps": 30,
+      "guidance": 4,
+      "negativePrompt": "artifacts, halos"
+    }
+  }'
+```
+
+```python Python
+requests.post(
+    f"{base}/jobs",
+    headers=headers,
+    json={
+        "type": "image.edit",
+        "inputs": {"images": ["https://cdn.rendobar.com/assets/examples/photo.jpg"]},
+        "params": {
+            "prompt": "Turn the daytime sky into a clear starry night",
+            "model": "qwen-image-edit-2511",
+            "steps": 30,
+            "guidance": 4,
+            "negativePrompt": "artifacts, halos",
+        },
+    },
+)
+```
+
+</CodeGroup>
+
+## The output
+
+A completed job carries a single webp file in `output.file`, typed `image`. `output.data` is `null`.
+
+```json
+{
+  "data": null,
+  "file": {
+    "url": "https://api.rendobar.com/dl/job_abc123?token=<token>",
+    "path": "output.webp",
+    "type": "image",
+    "size": 498000,
+    "meta": { "format": "webp", "width": 1024, "height": 1024 }
+  },
+  "files": [
+    { "url": "https://api.rendobar.com/dl/job_abc123?token=<token>", "path": "output.webp", "type": "image", "size": 498000, "meta": { "format": "webp", "width": 1024, "height": 1024 } }
+  ],
+  "expiresAt": 1735689600000
+}
+```
+
+The full [output shape](/concepts/job#the-output) is the same for every job type.
+
+## Parameters
+
+<ParamField body="inputs.images" type="string[]" required>
+  One to four reference image URLs. A public link or an uploaded asset's content URL. The per-model cap applies.
+</ParamField>
+
+<ParamField body="prompt" type="string" required>
+  The change to make, in plain language. No masks, no coordinates. Up to 4000 characters.
+</ParamField>
+
+<ParamField body="model" type="string" default="economy">
+  A tier alias (`economy`, `standard`, `premium`) or an exact model id. A tier lets the platform pick the model. A pinned id unlocks that model's own controls.
+</ParamField>
+
+<ParamField body="width" type="integer">
+  Requested output width in pixels. Defaults to the first reference image. Snapped to what the model can render.
+</ParamField>
+
+<ParamField body="height" type="integer">
+  Requested output height in pixels. Defaults to the first reference image.
+</ParamField>
+
+<ParamField body="seed" type="integer">
+  A fixed seed makes the result reproducible. Omit it for a fresh result each time.
+</ParamField>
+
+<ParamField body="enhancePrompt" type="boolean">
+  Rewrite the instruction for the model before editing. The default is per model, so omit it to keep the model's own default. `qwen-image-edit-2511` enhances by default, the lighter models do not.
+</ParamField>
+
+<ParamField body="steps" type="integer">
+  Denoise steps. More steps means more detail and more time. Requires a pinned model that exposes steps. The accepted range depends on the model.
+</ParamField>
+
+<ParamField body="guidance" type="number">
+  How strictly to follow the instruction. Higher is stricter. Range 1 to 10. Requires `qwen-image-edit-2511`.
+</ParamField>
+
+<ParamField body="negativePrompt" type="string">
+  What to keep out of the edited image. Up to 1000 characters. Requires `qwen-image-edit-2511`.
+</ParamField>
+
+## Discover models
+
+`GET /models?job=image.edit` lists the edit models with their reference-image caps, controls, and estimated cost.
+
+```bash
+curl "https://api.rendobar.com/models?job=image.edit" \
+  -H "Authorization: Bearer rb_YOUR_KEY"
+```
+
+## See also
+
+- [Generation API](/concepts/generation): the modalities and the shared model catalog
+- [Image generate](/jobs/image-generate): make an image from a text prompt
+- [Job output](/concepts/job#the-output): the output shape every job returns
+- [SDK](/sdk): `jobs.run`, uploads, and reading the output
+- [Webhooks](/guides/webhooks): receive `job.completed` instead of polling
diff --git a/jobs/image-generate.mdx b/jobs/image-generate.mdx
new file mode 100644
index 0000000..8082f1f
--- /dev/null
+++ b/jobs/image-generate.mdx
@@ -0,0 +1,280 @@
+---
+title: "Generate an image from a prompt"
+sidebarTitle: "Image generate"
+description: "Generate a webp image from a text prompt on hosted diffusion models. Pick an economy, standard, or premium tier, or pin an exact model id."
+icon: "image"
+keywords: ["image generation api", "text to image api", "flux api", "qwen image api", "ai image api", "diffusion api", "generate image from prompt", "webp image api", "text to image rest api"]
+canonical: "https://rendobar.com/docs/jobs/image-generate"
+---
+
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "TechArticle",
+      "@id": "https://rendobar.com/docs/jobs/image-generate/#article",
+      "headline": "Generate an image from a prompt",
+      "description": "Generate a webp image from a text prompt on hosted diffusion models. Pick an economy, standard, or premium tier, or pin an exact model id.",
+      "datePublished": "2026-07-26",
+      "dateModified": "2026-07-26",
+      "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
+      "isPartOf": { "@id": "https://rendobar.com/#website" }
+    })
+  }}
+/>
+
+`image.generate` turns a text prompt into an image on a hosted diffusion model. Ask for a tier and the platform picks the model, or pin an exact model id to reach its own controls. The result is a webp file returned as a signed URL, the same async job shape as everything else on Rendobar.
+
+This is one product in [Rendobar's Generation API](/concepts/generation).
+
+## Generate an image
+
+<CodeGroup>
+
+```ts SDK
+import { createClient, outputUrl } from "@rendobar/sdk";
+
+const client = createClient({ apiKey: "rb_YOUR_KEY" });
+
+// jobs.run submits and waits for the finished job in one call.
+const job = await client.jobs.run({
+  type: "image.generate",
+  params: {
+    prompt:
+      "A ceramic pour-over coffee dripper on a walnut counter, morning light from the left, soft shadows",
+    width: 1024,
+    height: 1024,
+  },
+});
+
+console.log(outputUrl(job)); // signed URL to the webp
+```
+
+```bash cURL
+curl -X POST "https://api.rendobar.com/jobs" \
+  -H "Authorization: Bearer rb_YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "image.generate",
+    "params": {
+      "prompt": "A ceramic pour-over coffee dripper on a walnut counter, morning light from the left, soft shadows",
+      "width": 1024,
+      "height": 1024
+    }
+  }'
+# Returns { "data": { "id": "job_...", "status": "waiting" } }.
+# Poll GET /jobs/{id} until "status": "complete".
+```
+
+```python Python
+import requests, time
+
+base = "https://api.rendobar.com"
+headers = {"Authorization": "Bearer rb_YOUR_KEY"}
+
+job = requests.post(
+    f"{base}/jobs",
+    headers=headers,
+    json={
+        "type": "image.generate",
+        "params": {
+            "prompt": "A ceramic pour-over coffee dripper on a walnut counter, morning light from the left, soft shadows",
+            "width": 1024,
+            "height": 1024,
+        },
+    },
+).json()["data"]
+
+while job["status"] not in ("complete", "failed", "cancelled"):
+    time.sleep(1)
+    job = requests.get(f"{base}/jobs/{job['id']}", headers=headers).json()["data"]
+
+print(job["output"]["file"]["url"])  # the webp
+```
+
+</CodeGroup>
+
+No `inputs` are needed. The prompt is the whole request. Every generation job is async, so you submit, then poll, [wait](/sdk#wait), or receive a [webhook](/guides/webhooks).
+
+## The output
+
+A completed job carries a single webp file in `output.file`. `output.data` is `null`, because generation writes a file rather than computing an answer.
+
+```json
+{
+  "data": null,
+  "file": {
+    "url": "https://api.rendobar.com/dl/job_abc123?token=<token>",
+    "path": "output.webp",
+    "type": "image",
+    "size": 512000,
+    "meta": { "format": "webp", "width": 1024, "height": 1024 }
+  },
+  "files": [
+    { "url": "https://api.rendobar.com/dl/job_abc123?token=<token>", "path": "output.webp", "type": "image", "size": 512000, "meta": { "format": "webp", "width": 1024, "height": 1024 } }
+  ],
+  "expiresAt": 1735689600000
+}
+```
+
+The real dimensions are in `output.file.meta`. Each model snaps your requested `width` and `height` to a size it can render, so the returned image can differ from what you asked for. The full [output shape](/concepts/job#the-output) is the same for every job type.
+
+## Tiers and models
+
+Set `model` to a tier alias for a price and quality posture without naming a model, or pin an exact model id to reach that model's own controls. Omit `model` and you get the `economy` tier.
+
+<CodeGroup>
+
+```ts SDK
+// Tier alias: the platform picks the model.
+await client.jobs.run({
+  type: "image.generate",
+  params: { prompt: "A red bicycle leaning on a brick wall", model: "premium" },
+});
+
+// Pinned model id: unlocks that model's own controls.
+await client.jobs.run({
+  type: "image.generate",
+  params: {
+    prompt: "A red bicycle leaning on a brick wall",
+    model: "qwen-image-2512",
+    steps: 40,
+    guidance: 4.5,
+    negativePrompt: "blurry, low quality",
+  },
+});
+```
+
+```bash cURL
+curl -X POST "https://api.rendobar.com/jobs" \
+  -H "Authorization: Bearer rb_YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "image.generate",
+    "params": { "prompt": "A red bicycle leaning on a brick wall", "model": "premium" }
+  }'
+```
+
+```python Python
+requests.post(
+    f"{base}/jobs",
+    headers=headers,
+    json={
+        "type": "image.generate",
+        "params": {"prompt": "A red bicycle leaning on a brick wall", "model": "premium"},
+    },
+)
+```
+
+</CodeGroup>
+
+The three tiers map to these models today. Aliases can be re-pointed as the catalog grows, so pin an exact id when you need a result to stay stable.
+
+| Tier | Model | Est. USD per image | Controls | Best for |
+|---|---|---|---|---|
+| `economy` (default) | `flux-2-klein-4b` | 0.0009 | prompt only | Drafts and fast iteration at the lowest cost |
+| `standard` | `ernie-image-turbo` | 0.0027 | prompt only | Everyday images with balanced quality |
+| `premium` | `qwen-image-2512` | 0.0394 | steps, guidance, negative prompt | Highest fidelity with full control |
+
+You can also pin a model that no tier points at:
+
+| Model | Est. USD per image | Controls | Best for |
+|---|---|---|---|
+| `z-image-turbo` | 0.002 | steps (8 to 12) | A very fast turbo model |
+| `qwen-image-2512-lightning` | 0.0037 | steps (4 to 8) | Qwen quality at turbo speed |
+| `flux-2-dev` | 0.0378 | steps (10 to 50), guidance | FLUX.2 quality with guidance control |
+
+<Info>
+The USD figures are per-image cost estimates, the same values [`GET /models`](#discover-models) returns. They are estimates, not a fixed price. Jobs bill on the compute they use, cost-plus. See [credits and billing](/concepts/credits).
+</Info>
+
+## Model-specific controls
+
+Tier aliases accept the base fields only. To use `steps`, `guidance`, or `negativePrompt`, pin an exact model id. Sending a control the resolved model does not support returns `VALIDATION_ERROR` before anything is billed.
+
+| Control | Models that accept it | Range |
+|---|---|---|
+| `steps` | `z-image-turbo`, `qwen-image-2512`, `qwen-image-2512-lightning`, `flux-2-dev` | Per model, see table above |
+| `guidance` | `qwen-image-2512`, `flux-2-dev` | 1 to 10 |
+| `negativePrompt` | `qwen-image-2512` | Up to 1000 characters |
+
+`flux-2-klein-4b` and `ernie-image-turbo` fix their own step count and expose the base fields only.
+
+## Parameters
+
+<ParamField body="prompt" type="string" required>
+  What you want, in plain language. No special syntax. Up to 4000 characters.
+</ParamField>
+
+<ParamField body="model" type="string" default="economy">
+  A tier alias (`economy`, `standard`, `premium`) or an exact model id. A tier lets the platform pick the model. A pinned id unlocks that model's own controls.
+</ParamField>
+
+<ParamField body="width" type="integer">
+  Requested output width in pixels. Snapped to what the model can render. The real size comes back in `output.file.meta`.
+</ParamField>
+
+<ParamField body="height" type="integer">
+  Requested output height in pixels. Snapped to what the model can render.
+</ParamField>
+
+<ParamField body="seed" type="integer">
+  A fixed seed makes the result reproducible. Omit it for a fresh random image each time.
+</ParamField>
+
+<ParamField body="enhancePrompt" type="boolean">
+  Rewrite the prompt for the model before generating. The default is per model, so omit it to keep the model's own default. `qwen-image-2512` enhances by default, the lighter models do not.
+</ParamField>
+
+<ParamField body="steps" type="integer">
+  Denoise steps. More steps means more detail and more time. Requires a pinned model that exposes steps. The accepted range depends on the model.
+</ParamField>
+
+<ParamField body="guidance" type="number">
+  How strictly to follow the prompt. Higher is stricter. Range 1 to 10. Requires `qwen-image-2512` or `flux-2-dev`.
+</ParamField>
+
+<ParamField body="negativePrompt" type="string">
+  What to keep out of the image. Up to 1000 characters. Requires `qwen-image-2512`.
+</ParamField>
+
+## Discover models
+
+`GET /models` lists every generation model with its tier, capabilities, step range, and estimated cost, so a model picker never has to hardcode the catalog. Filter to one job type with `?job=`.
+
+```bash
+curl "https://api.rendobar.com/models?job=image.generate" \
+  -H "Authorization: Bearer rb_YOUR_KEY"
+```
+
+```json
+{
+  "data": [
+    {
+      "id": "flux-2-klein-4b",
+      "jobs": ["image.generate", "image.edit"],
+      "tier": "economy",
+      "estCostUsd": 0.0009,
+      "maxRefImages": 4,
+      "steps": null,
+      "supports": { "negativePrompt": false, "guidance": false },
+      "enhanceDefault": false,
+      "status": "active"
+    }
+  ]
+}
+```
+
+## Errors
+
+A bad request fails on `POST /jobs` before anything is billed. An unknown model id, or a control the resolved model does not support, returns `VALIDATION_ERROR`. After the job starts, failures carry the standard [error](/support/errors) shape.
+
+## See also
+
+- [Generation API](/concepts/generation): the modalities and the shared model catalog
+- [Image edit](/jobs/image-edit): change an existing image from an instruction
+- [Job output](/concepts/job#the-output): the output shape every job returns
+- [SDK](/sdk): `jobs.run`, `jobs.wait`, and reading the output
+- [Webhooks](/guides/webhooks): receive `job.completed` instead of polling

From a74f93e57d60d38379fa8503d7aed76e10ef45d2 Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Fri, 31 Jul 2026 11:24:40 +0300
Subject: [PATCH 2/3] docs: correct the generation model catalog and document
 previews

The tier table predated the 2026-07-29 catalog change: standard resolves to
z-image-turbo, not ernie-image-turbo, and both ernie-image-turbo and
qwen-image-2512-lightning are under review, so pinning either one is rejected
at submit. The pages also documented estCostUsd, which GET /models no longer
returns; priceTier replaced it. Preview streaming shipped with the jobs but
was never documented.

- Rebuild both tier tables from gen-registry.ts
- Replace every dollar figure with the relative priceTier
- Document underReview and the VALIDATION_ERROR it produces
- Fix the GET /models sample to the shape the route actually returns
- Correct enhancePrompt: no model in the catalog enhances by default
- Add a preview streaming section with the job.preview field reference
- Note the 4096px dimension cap
---
 concepts/generation.mdx | 15 ++++++----
 jobs/image-edit.mdx     | 35 +++++++++++++++-------
 jobs/image-generate.mdx | 65 ++++++++++++++++++++++++++++++-----------
 3 files changed, 83 insertions(+), 32 deletions(-)

diff --git a/concepts/generation.mdx b/concepts/generation.mdx
index c642cf0..3d3ed1d 100644
--- a/concepts/generation.mdx
+++ b/concepts/generation.mdx
@@ -17,7 +17,7 @@ canonical: "https://rendobar.com/docs/concepts/generation"
       "headline": "The Generation API",
       "description": "Generate images from a text prompt or edit them from an instruction on hosted diffusion models. One async API, one job shape, many models.",
       "datePublished": "2026-07-26",
-      "dateModified": "2026-07-26",
+      "dateModified": "2026-07-31",
       "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
       "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
       "isPartOf": { "@id": "https://rendobar.com/#website" }
@@ -53,7 +53,7 @@ Tier aliases can be re-pointed to newer models as the catalog grows. Pin an exac
 
 ## Discover models
 
-`GET /models` returns the live catalog: every model with its supported jobs, tier, capabilities, step range, and an estimated per-image cost. Filter to one job type with `?job=`. Build a model picker against this endpoint instead of hardcoding the list.
+`GET /models` returns the live catalog: every model with its supported jobs, tier, relative price, capabilities, and step range. Filter to one job type with `?job=`. Build a model picker against this endpoint instead of hardcoding the list.
 
 ```bash
 curl "https://api.rendobar.com/models" \
@@ -67,23 +67,28 @@ curl "https://api.rendobar.com/models" \
       "id": "qwen-image-2512",
       "jobs": ["image.generate"],
       "tier": "premium",
-      "estCostUsd": 0.0394,
+      "underReview": false,
+      "priceTier": "$$$$",
       "maxRefImages": 0,
       "steps": { "default": 50, "min": 20, "max": 50 },
       "supports": { "negativePrompt": true, "guidance": true },
-      "enhanceDefault": true,
+      "enhanceDefault": false,
       "status": "active"
     }
   ]
 }
 ```
 
-The `estCostUsd` field is an estimate to help you compare models, not a fixed price. Jobs bill on the compute they use, cost-plus. See [credits and billing](/concepts/credits).
+`priceTier` compares models against each other, from `$` to `$$$$`. It is not a per-image charge, because jobs bill on the compute they actually use, cost-plus. See [credits and billing](/concepts/credits).
+
+A model with `underReview: true` is pulled from tier resolution while we re-evaluate its cost and quality. It stays listed so a caller pinning it can see why the submit was rejected, but no tier resolves to it and pinning it returns `VALIDATION_ERROR`.
 
 ## Same job, same shape
 
 A generation job is a [job](/concepts/job) like any other. You submit it to `POST /jobs`, it runs async, and you poll, [wait](/sdk#wait), or receive a [webhook](/guides/webhooks). The image jobs return a single webp file in `output.file`, with `output.data` set to `null`.
 
+One thing is specific to generation. While the model denoises, the job emits `job.preview` events carrying a small frame of the image as it resolves, so a client can show the picture arriving instead of a spinner. Previews are decoration: they are never replayed, and a model can emit none. See [watch it render](/jobs/image-generate#watch-it-render).
+
 ```ts
 import { createClient, outputUrl } from "@rendobar/sdk";
 
diff --git a/jobs/image-edit.mdx b/jobs/image-edit.mdx
index 27e21e9..10e23a5 100644
--- a/jobs/image-edit.mdx
+++ b/jobs/image-edit.mdx
@@ -17,7 +17,7 @@ canonical: "https://rendobar.com/docs/jobs/image-edit"
       "headline": "Edit an image with an instruction",
       "description": "Use a written instruction to edit one to four reference images on hosted diffusion models. Swap a background, restyle, or compose.",
       "datePublished": "2026-07-26",
-      "dateModified": "2026-07-26",
+      "dateModified": "2026-07-31",
       "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
       "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
       "isPartOf": { "@id": "https://rendobar.com/#website" }
@@ -107,14 +107,16 @@ Passing more images than the resolved model accepts returns `VALIDATION_ERROR` b
 
 Set `model` to a tier alias or pin an exact model id. Omit it and you get the `economy` tier. Aliases can be re-pointed as the catalog grows, so pin an exact id when you need a result to stay stable.
 
-| Tier | Model | Est. USD per image | Reference images | Controls |
+| Tier | Model | Price | Reference images | Controls when pinned |
 |---|---|---|---|---|
-| `economy` (default) | `flux-2-klein-4b` | 0.0009 | Up to 4 | prompt only |
-| `standard` | `qwen-image-edit-2511-lightning` | 0.0024 | Up to 3 | steps (4 to 8) |
-| `premium` | `qwen-image-edit-2511` | 0.033 | Up to 3 | steps (20 to 40), guidance, negative prompt |
+| `economy` (default) | `flux-2-klein-4b` | `$` | Up to 4 | prompt only |
+| `standard` | `qwen-image-edit-2511-lightning` | `$$$` | Up to 3 | steps (4 to 8) |
+| `premium` | `qwen-image-edit-2511` | `$$$$` | Up to 3 | steps (20 to 40), guidance, negative prompt |
+
+Every `image.edit` model is reachable through a tier. There is no pin-only model on this job type today.
 
 <Info>
-The USD figures are per-image cost estimates, the same values [`GET /models`](#discover-models) returns. They are estimates, not a fixed price. Jobs bill on the compute they use, cost-plus. See [credits and billing](/concepts/credits).
+`Price` is the model's `priceTier`, a relative comparison from `$` to `$$$$`. It is not a per-image charge. Jobs bill on the compute they actually use, cost-plus. See [credits and billing](/concepts/credits).
 </Info>
 
 ## Model-specific controls
@@ -197,6 +199,19 @@ A completed job carries a single webp file in `output.file`, typed `image`. `out
 
 The full [output shape](/concepts/job#the-output) is the same for every job type.
 
+## Watch it render
+
+An edit job emits `job.preview` events while the model denoises, each carrying a small webp frame. Subscribe with the SDK to show the edit resolving instead of a spinner.
+
+```ts
+const sub = client.realtime.subscribeJob(created.id, {
+  onPreview: (e) => setPreview(`data:image/webp;base64,${e.data}`),
+  onComplete: (job) => sub.unsubscribe(),
+});
+```
+
+Previews are decoration and never hold up a job. The `standard` tier finishes in four steps, so it usually completes before a frame is worth showing. See [the field reference](/jobs/image-generate#watch-it-render) on the generate page.
+
 ## Parameters
 
 <ParamField body="inputs.images" type="string[]" required>
@@ -212,11 +227,11 @@ The full [output shape](/concepts/job#the-output) is the same for every job type
 </ParamField>
 
 <ParamField body="width" type="integer">
-  Requested output width in pixels. Defaults to the first reference image. Snapped to what the model can render.
+  Requested output width in pixels, up to 4096. Defaults to the first reference image. Snapped to what the model can render.
 </ParamField>
 
 <ParamField body="height" type="integer">
-  Requested output height in pixels. Defaults to the first reference image.
+  Requested output height in pixels, up to 4096. Defaults to the first reference image.
 </ParamField>
 
 <ParamField body="seed" type="integer">
@@ -224,7 +239,7 @@ The full [output shape](/concepts/job#the-output) is the same for every job type
 </ParamField>
 
 <ParamField body="enhancePrompt" type="boolean">
-  Rewrite the instruction for the model before editing. The default is per model, so omit it to keep the model's own default. `qwen-image-edit-2511` enhances by default, the lighter models do not.
+  Rewrite the instruction for the model before editing. Off by default on every model in the catalog today. The default is per model (`enhanceDefault` in [`GET /models`](#discover-models)), so omit it to keep whatever the model ships with.
 </ParamField>
 
 <ParamField body="steps" type="integer">
@@ -241,7 +256,7 @@ The full [output shape](/concepts/job#the-output) is the same for every job type
 
 ## Discover models
 
-`GET /models?job=image.edit` lists the edit models with their reference-image caps, controls, and estimated cost.
+`GET /models?job=image.edit` lists the edit models with their reference-image caps, controls, and relative price. The [response shape](/jobs/image-generate#discover-models) is the same for both generation job types.
 
 ```bash
 curl "https://api.rendobar.com/models?job=image.edit" \
diff --git a/jobs/image-generate.mdx b/jobs/image-generate.mdx
index 8082f1f..e6a4ab8 100644
--- a/jobs/image-generate.mdx
+++ b/jobs/image-generate.mdx
@@ -17,7 +17,7 @@ canonical: "https://rendobar.com/docs/jobs/image-generate"
       "headline": "Generate an image from a prompt",
       "description": "Generate a webp image from a text prompt on hosted diffusion models. Pick an economy, standard, or premium tier, or pin an exact model id.",
       "datePublished": "2026-07-26",
-      "dateModified": "2026-07-26",
+      "dateModified": "2026-07-31",
       "author": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
       "publisher": { "@type": "Organization", "@id": "https://rendobar.com/#organization" },
       "isPartOf": { "@id": "https://rendobar.com/#website" }
@@ -121,6 +121,30 @@ A completed job carries a single webp file in `output.file`. `output.data` is `n
 
 The real dimensions are in `output.file.meta`. Each model snaps your requested `width` and `height` to a size it can render, so the returned image can differ from what you asked for. The full [output shape](/concepts/job#the-output) is the same for every job type.
 
+## Watch it render
+
+A generation job emits `job.preview` events while the model denoises, each carrying a small webp frame. Subscribe with the SDK to show the picture resolving instead of a spinner.
+
+```ts
+const sub = client.realtime.subscribeJob(created.id, {
+  onPreview: (e) => {
+    // e.data is base64 webp, roughly 256px on its long edge.
+    setPreview(`data:image/webp;base64,${e.data}`);
+    setBlur((1 - (e.progress ?? 0)) * 20); // ease the blur out as it sharpens
+  },
+  onComplete: (job) => sub.unsubscribe(),
+});
+```
+
+| Field | Meaning |
+|---|---|
+| `seq` | Monotonic per job. Drop any frame whose `seq` is at or below the last one you rendered. |
+| `progress` | Denoise progress from 0 to 1 at capture, or `null` when the model does not report it. |
+| `width` / `height` | Dimensions of the preview frame, not of the final image. |
+| `data` | Base64 webp, roughly 256px on its long edge. |
+
+Previews are decoration and never hold up a job. They are ephemeral: nothing is replayed on reconnect, and a late subscriber sees only the newest frame. A model with no fast decoder emits none, and a four-step model resolves too late to be worth watching. Build for zero frames and treat anything you get as a bonus.
+
 ## Tiers and models
 
 Set `model` to a tier alias for a price and quality posture without naming a model, or pin an exact model id to reach that model's own controls. Omit `model` and you get the `economy` tier.
@@ -172,35 +196,39 @@ requests.post(
 
 The three tiers map to these models today. Aliases can be re-pointed as the catalog grows, so pin an exact id when you need a result to stay stable.
 
-| Tier | Model | Est. USD per image | Controls | Best for |
+| Tier | Model | Price | Controls when pinned | Best for |
 |---|---|---|---|---|
-| `economy` (default) | `flux-2-klein-4b` | 0.0009 | prompt only | Drafts and fast iteration at the lowest cost |
-| `standard` | `ernie-image-turbo` | 0.0027 | prompt only | Everyday images with balanced quality |
-| `premium` | `qwen-image-2512` | 0.0394 | steps, guidance, negative prompt | Highest fidelity with full control |
+| `economy` (default) | `flux-2-klein-4b` | `$` | prompt only | Drafts and fast iteration at the lowest cost |
+| `standard` | `z-image-turbo` | `$$` | steps (8 to 12) | Everyday images at turbo speed |
+| `premium` | `qwen-image-2512` | `$$$$` | steps, guidance, negative prompt | Highest fidelity with full control |
 
 You can also pin a model that no tier points at:
 
-| Model | Est. USD per image | Controls | Best for |
+| Model | Price | Controls | Best for |
 |---|---|---|---|
-| `z-image-turbo` | 0.002 | steps (8 to 12) | A very fast turbo model |
-| `qwen-image-2512-lightning` | 0.0037 | steps (4 to 8) | Qwen quality at turbo speed |
-| `flux-2-dev` | 0.0378 | steps (10 to 50), guidance | FLUX.2 quality with guidance control |
+| `flux-2-dev` | `$$$$` | steps (10 to 50), guidance | FLUX.2 quality with guidance control |
 
 <Info>
-The USD figures are per-image cost estimates, the same values [`GET /models`](#discover-models) returns. They are estimates, not a fixed price. Jobs bill on the compute they use, cost-plus. See [credits and billing](/concepts/credits).
+`Price` is the model's `priceTier`, a relative comparison from `$` to `$$$$`. It is not a per-image charge. Jobs bill on the compute they actually use, cost-plus, so a slower model on a bigger GPU costs more per image. See [credits and billing](/concepts/credits).
 </Info>
 
+### Models under review
+
+A model can be pulled from tier resolution while we re-evaluate its cost and quality. It stays in [`GET /models`](#discover-models) with `underReview: true`, and pinning it returns `VALIDATION_ERROR` at submit before anything is billed.
+
+`ernie-image-turbo` and `qwen-image-2512-lightning` are under review today. Use a tier, or pin one of the models above.
+
 ## Model-specific controls
 
 Tier aliases accept the base fields only. To use `steps`, `guidance`, or `negativePrompt`, pin an exact model id. Sending a control the resolved model does not support returns `VALIDATION_ERROR` before anything is billed.
 
 | Control | Models that accept it | Range |
 |---|---|---|
-| `steps` | `z-image-turbo`, `qwen-image-2512`, `qwen-image-2512-lightning`, `flux-2-dev` | Per model, see table above |
+| `steps` | `z-image-turbo`, `qwen-image-2512`, `flux-2-dev` | Per model, see table above |
 | `guidance` | `qwen-image-2512`, `flux-2-dev` | 1 to 10 |
 | `negativePrompt` | `qwen-image-2512` | Up to 1000 characters |
 
-`flux-2-klein-4b` and `ernie-image-turbo` fix their own step count and expose the base fields only.
+`flux-2-klein-4b` fixes its own step count and exposes the base fields only.
 
 ## Parameters
 
@@ -213,11 +241,11 @@ Tier aliases accept the base fields only. To use `steps`, `guidance`, or `negati
 </ParamField>
 
 <ParamField body="width" type="integer">
-  Requested output width in pixels. Snapped to what the model can render. The real size comes back in `output.file.meta`.
+  Requested output width in pixels, up to 4096. Snapped to what the model can render. The real size comes back in `output.file.meta`.
 </ParamField>
 
 <ParamField body="height" type="integer">
-  Requested output height in pixels. Snapped to what the model can render.
+  Requested output height in pixels, up to 4096. Snapped to what the model can render.
 </ParamField>
 
 <ParamField body="seed" type="integer">
@@ -225,7 +253,7 @@ Tier aliases accept the base fields only. To use `steps`, `guidance`, or `negati
 </ParamField>
 
 <ParamField body="enhancePrompt" type="boolean">
-  Rewrite the prompt for the model before generating. The default is per model, so omit it to keep the model's own default. `qwen-image-2512` enhances by default, the lighter models do not.
+  Rewrite the prompt for the model before generating. Off by default on every model in the catalog today. The default is per model (`enhanceDefault` in [`GET /models`](#discover-models)), so omit it to keep whatever the model ships with.
 </ParamField>
 
 <ParamField body="steps" type="integer">
@@ -242,7 +270,7 @@ Tier aliases accept the base fields only. To use `steps`, `guidance`, or `negati
 
 ## Discover models
 
-`GET /models` lists every generation model with its tier, capabilities, step range, and estimated cost, so a model picker never has to hardcode the catalog. Filter to one job type with `?job=`.
+`GET /models` lists every generation model with its tier, relative price, capabilities, and step range, so a model picker never has to hardcode the catalog. Filter to one job type with `?job=`.
 
 ```bash
 curl "https://api.rendobar.com/models?job=image.generate" \
@@ -256,7 +284,8 @@ curl "https://api.rendobar.com/models?job=image.generate" \
       "id": "flux-2-klein-4b",
       "jobs": ["image.generate", "image.edit"],
       "tier": "economy",
-      "estCostUsd": 0.0009,
+      "underReview": false,
+      "priceTier": "$",
       "maxRefImages": 4,
       "steps": null,
       "supports": { "negativePrompt": false, "guidance": false },
@@ -267,6 +296,8 @@ curl "https://api.rendobar.com/models?job=image.generate" \
 }
 ```
 
+Read `tier` to group models, `priceTier` to sort them by cost, and `underReview` to grey out the ones that will not run. `steps` is `null` on a model that fixes its own step count.
+
 ## Errors
 
 A bad request fails on `POST /jobs` before anything is billed. An unknown model id, or a control the resolved model does not support, returns `VALIDATION_ERROR`. After the job starts, failures carry the standard [error](/support/errors) shape.

From 6f4933af24b9117e2b9918522c29641d910b6e9c Mon Sep 17 00:00:00 2001
From: Abdelrahman Essawy <abdelrahman.mo.essawy@gmail.com>
Date: Fri, 31 Jul 2026 14:10:38 +0300
Subject: [PATCH 3/3] fix: bring the compress description within the
 frontmatter rules

The validator has failed on main for the last five merges: the description
runs 183 chars against a 160 cap and opens with "Compress", which is not in
the allowed start-verb list. Rewritten to 155 chars starting with "Get".
---
 jobs/compress.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/jobs/compress.mdx b/jobs/compress.mdx
index 26dd0ed..282f52f 100644
--- a/jobs/compress.mdx
+++ b/jobs/compress.mdx
@@ -1,7 +1,7 @@
 ---
 title: "Compress media to a target quality or size"
 sidebarTitle: "Compress"
-description: "Compress an image, video, or audio file to the smallest size that clears a perceptual quality bar, or hit a byte budget and get the quality scored. AVIF, JPEG XL, AV1, Opus, and more."
+description: "Get an image, video, or audio file down to a target quality or byte budget. The encoder searches candidate encodes and returns the smallest that clears it."
 icon: "file-zipper"
 keywords: ["image compression api", "video compression api", "compress to target size api", "avif api", "jpeg xl api", "smallest file at quality", "ssimulacra2 api", "vmaf api", "compress video to 1mb", "audio compression api"]
 canonical: "https://rendobar.com/docs/jobs/compress"