From 60756d59d59b8c69d7760cea32132b1c54c6b866 Mon Sep 17 00:00:00 2001 From: Dervlex Date: Fri, 22 May 2026 00:13:59 +0200 Subject: [PATCH 1/2] docs(image): document gpt-image-2 / gpt-image-2-edit `quality` parameter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `quality` parameter (`low | medium | high`, default `high`) is now honored end-to-end for `gpt-image-2` and `gpt-image-2-edit` by web, public API, and SDK clients — no opt-in header required. Mobile clients remain on the legacy fixed price schedule until they ship their own quality UI. Adds: - Quality-tier explanation + example to /image/generate, /image/edit, and /image/multi-edit endpoint docs. - `model_spec.pricing.quality` matrix example to /models endpoint doc. - Quality-tier pricing tables (1K/2K/4K × low/medium/high) to the pricing overview, with prices computed from the live FAL base rates plus the standard 1.15× markup. - Note in the image-models landing page pointing to the matrix. - `quality` property on `GenerateImageRequest`, `EditImageRequest`, `MultiEditImageRequest`, and `MultiEditImageMultipartRequest` in swagger.yaml. (The OpenAI-compat `/v1/image/generations` schema keeps its passthrough-only `quality` description — that endpoint still ignores the field for parity with OpenAI.) Replaces the earlier draft branch (`docs/gpt-image-2-dynamic-pricing`) which described an unimplemented token-based pricing model. This branch matches what production actually exposes. --- api-reference/endpoint/image/edit.mdx | 22 +++++++++- api-reference/endpoint/image/generate.mdx | 20 +++++++++ api-reference/endpoint/image/multi-edit.mdx | 20 +++++++++ api-reference/endpoint/models/list.mdx | 33 ++++++++++++++ models/image.mdx | 4 ++ overview/pricing.mdx | 28 +++++++++++- swagger.yaml | 48 +++++++++++++++++++++ 7 files changed, 172 insertions(+), 3 deletions(-) diff --git a/api-reference/endpoint/image/edit.mdx b/api-reference/endpoint/image/edit.mdx index 3f38cdc..8184634 100644 --- a/api-reference/endpoint/image/edit.mdx +++ b/api-reference/endpoint/image/edit.mdx @@ -10,7 +10,27 @@ This is an experimental endpoint and may be subject to change. -**Pricing:** Image editing/inpainting pricing varies by model. The default model (`qwen-edit`) is **$0.04 per edit**. See the [Models endpoint](/api-reference/endpoint/models/list) for all available inpaint models and their pricing. +**Pricing:** Image editing pricing varies by model. The default model (`qwen-edit`) is **$0.04 per edit**. See the [Models endpoint](/api-reference/endpoint/models/list) for all available edit models and their pricing. + + +## Quality Tiers + +Some edit models accept an optional `quality` parameter (`low`, `medium`, `high`) that trades visual fidelity for cost. Currently supported by `gpt-image-2-edit`; other models ignore the parameter. + +```json +{ + "model": "gpt-image-2-edit", + "image": "iVBORw0KGgo...", + "prompt": "change the sky to a sunrise", + "resolution": "2K", + "quality": "medium" +} +``` + +When you omit `quality`, the model uses its default tier (`high` for `gpt-image-2-edit`). Per-tier prices (1K/2K/4K × low/medium/high) live under `model_spec.pricing.quality` in the [Models endpoint](/api-reference/endpoint/models/list) and are listed in the [Pricing overview](/overview/pricing). + + +**Mobile clients** stay on the legacy fixed price schedule until the mobile app ships its own quality selector. Web, public API, and SDK callers automatically use the quality-aware pricing path; no opt-in header is required. ## Postman Collection diff --git a/api-reference/endpoint/image/generate.mdx b/api-reference/endpoint/image/generate.mdx index e8a9dc5..25945f8 100644 --- a/api-reference/endpoint/image/generate.mdx +++ b/api-reference/endpoint/image/generate.mdx @@ -59,6 +59,26 @@ For models that use direct pixel dimensions, send `width` and `height` instead: Check [Image Models](/models/image) or the [Models endpoint](/api-reference/endpoint/models/list) for each model's supported sizing options before mixing sizing fields across models. +## Quality Tiers + +Some models accept an optional `quality` parameter (`low`, `medium`, `high`) that trades visual fidelity for cost. Currently supported by `gpt-image-2`; other models ignore the parameter. + +```json +{ + "model": "gpt-image-2", + "prompt": "a cinematic wide shot of Venice at sunset", + "aspect_ratio": "16:9", + "resolution": "2K", + "quality": "medium" +} +``` + +When you omit `quality`, the model uses its default tier (`high` for `gpt-image-2`). Pricing depends on the combination of `resolution` and `quality` — the per-tier prices for `gpt-image-2` (1K/2K/4K × low/medium/high) are exposed under `model_spec.pricing.quality` in the [Models endpoint](/api-reference/endpoint/models/list) and listed in the [Pricing overview](/overview/pricing). + + +**Mobile clients** are currently held back to the legacy fixed price schedule until the mobile app ships its own quality selector. Web, public API, and SDK callers automatically use the quality-aware pricing path; no opt-in header is required. + + ## Postman Collection For additional examples, please see this [Postman Collection](https://www.postman.com/veniceai/workspace/venice-ai-workspace/folder/38652128-0adc004d-2edf-4b88-a3bb-0f868c791c9c?action=share&source=copy-link&creator=38652128&ctx=documentation). diff --git a/api-reference/endpoint/image/multi-edit.mdx b/api-reference/endpoint/image/multi-edit.mdx index 098b347..77842de 100644 --- a/api-reference/endpoint/image/multi-edit.mdx +++ b/api-reference/endpoint/image/multi-edit.mdx @@ -9,3 +9,23 @@ openapi: 'POST /image/multi-edit' **Pricing:** Multi-edit pricing varies by model. See the [Pricing overview](/overview/pricing) for current per-edit prices. + +## Quality Tiers + +Some multi-edit models accept an optional `quality` parameter (`low`, `medium`, `high`) that trades visual fidelity for cost. Currently supported by `gpt-image-2-edit`; other models ignore the parameter. + +```json +{ + "modelId": "gpt-image-2-edit", + "images": ["iVBORw0KGgo...", "iVBORw0KGgo..."], + "prompt": "blend the two scenes into one cinematic frame", + "resolution": "2K", + "quality": "medium" +} +``` + +When you omit `quality`, the model uses its default tier (`high` for `gpt-image-2-edit`). Per-tier prices (1K/2K/4K × low/medium/high) live under `model_spec.pricing.quality` in the [Models endpoint](/api-reference/endpoint/models/list) and are listed in the [Pricing overview](/overview/pricing). + + +**Mobile clients** stay on the legacy fixed price schedule until the mobile app ships its own quality selector. Web, public API, and SDK callers automatically use the quality-aware pricing path; no opt-in header is required. + diff --git a/api-reference/endpoint/models/list.mdx b/api-reference/endpoint/models/list.mdx index 49648fc..6ac7c79 100644 --- a/api-reference/endpoint/models/list.mdx +++ b/api-reference/endpoint/models/list.mdx @@ -5,6 +5,39 @@ openapi: 'GET /models' "og:description": "Documentation covering Venice's model list API." --- +## Quality-Tier Pricing + +For image models that accept the optional `quality` parameter (currently `gpt-image-2` and `gpt-image-2-edit`), the response exposes a per-quality price matrix under `model_spec.pricing.quality`. Each top-level key is a resolution tier (`1K`, `2K`, `4K`) and each nested key is a quality level (`low`, `medium`, `high`) carrying its own `usd` and `diem` price: + +```json +"pricing": { + "resolutions": { + "1K": { "usd": 0.27, "diem": 0.27 }, + "2K": { "usd": 0.51, "diem": 0.51 }, + "4K": { "usd": 0.84, "diem": 0.84 } + }, + "quality": { + "1K": { + "low": { "usd": 0.02, "diem": 0.02 }, + "medium": { "usd": 0.07, "diem": 0.07 }, + "high": { "usd": 0.26, "diem": 0.26 } + }, + "2K": { + "low": { "usd": 0.03, "diem": 0.03 }, + "medium": { "usd": 0.13, "diem": 0.13 }, + "high": { "usd": 0.50, "diem": 0.50 } + }, + "4K": { + "low": { "usd": 0.05, "diem": 0.05 }, + "medium": { "usd": 0.21, "diem": 0.21 }, + "high": { "usd": 0.83, "diem": 0.83 } + } + } +} +``` + +`pricing.resolutions` reflects the legacy per-image schedule (used when no `quality` is sent by a legacy-billed client such as the Venice mobile app). `pricing.quality` is the matrix that applies to web, public API, and SDK callers — i.e. anyone using the `quality` parameter. Both are kept in the response so clients can detect quality support and surface the matrix in their own UIs. + ## Postman Collection For additional examples, please see this [Postman Collection](https://www.postman.com/veniceai/workspace/venice-ai-workspace/folder/38652128-59dfa959-7038-4cd8-b8ba-80cf09f2f026?action=share&source=copy-link&creator=38652128&ctx=documentation). diff --git a/models/image.mdx b/models/image.mdx index 25b5693..4594cfe 100644 --- a/models/image.mdx +++ b/models/image.mdx @@ -20,4 +20,8 @@ See the [Image Generate API](/api-reference/endpoint/image/generate) for text-to Image generation sizing is model-specific. Pixel-based models such as `venice-sd35` and `qwen-image` use `width` and `height`; aspect-ratio models such as `qwen-image-2` use `aspect_ratio`; models that list resolution options such as `1K`, `2K`, or `4K` use both `resolution` and `aspect_ratio`. + + + +**Quality tiers.** `gpt-image-2` (generate) and `gpt-image-2-edit` (edit/multi-edit) accept an optional `quality` parameter — `low`, `medium`, or `high` (default). Lower tiers cost less; see the [Pricing overview](/overview/pricing#quality-tier-pricing-gpt-image-2) for the full matrix or fetch `model_spec.pricing.quality` from the [Models endpoint](/api-reference/endpoint/models/list). \ No newline at end of file diff --git a/overview/pricing.mdx b/overview/pricing.mdx index ba0959f..783ca9a 100644 --- a/overview/pricing.mdx +++ b/overview/pricing.mdx @@ -133,7 +133,7 @@ Prices per 1M tokens unless noted. All prices in USD. 1 Diem = $1/day of compute | Model | ID | Price | Privacy | |---|---|---|---| | Recraft V4 Pro | `recraft-v4-pro` | Per Image: $0.29 | Anonymized | -| GPT Image 2 | `gpt-image-2` | 1K: $0.27, 2K: $0.51, 4K: $0.84 | Anonymized | +| GPT Image 2 | `gpt-image-2` | 1K: $0.26, 2K: $0.50, 4K: $0.83 (quality `high`, default) — see [tier matrix](#quality-tier-pricing-gpt-image-2) | Anonymized | | GPT Image 1.5 | `gpt-image-1-5` | Per Image: $0.26 | Anonymized | | Nano Banana Pro | `nano-banana-pro` | 1K: $0.18, 2K: $0.23, 4K: $0.35 | Anonymized | | Nano Banana 2 | `nano-banana-2` | 1K: $0.10, 2K: $0.14, 4K: $0.19 | Anonymized | @@ -172,7 +172,7 @@ Prices per 1M tokens unless noted. All prices in USD. 1 Diem = $1/day of compute | FireRed Image Edit 1.1 | `firered-image-edit` | $0.04 | | Flux 2 Max | `flux-2-max-edit` | $0.19 | | GPT Image 1.5 | `gpt-image-1-5-edit` | $0.36 | -| GPT Image 2 | `gpt-image-2-edit` | $0.36 | +| GPT Image 2 | `gpt-image-2-edit` | 1K: $0.36, 2K: $0.53, 4K: $0.86 (quality `high`, default) — see [tier matrix](#quality-tier-pricing-gpt-image-2) | | Grok Imagine | `grok-imagine-edit` | $0.04 | | Grok Imagine High Quality | `grok-imagine-quality-edit` | $0.10 | | Nano Banana 2 | `nano-banana-2-edit` | $0.10 | @@ -184,6 +184,30 @@ Prices per 1M tokens unless noted. All prices in USD. 1 Diem = $1/day of compute | Seedream V5 Lite | `seedream-v5-lite-edit` | $0.05 | | Wan 2.7 Pro Edit | `wan-2-7-pro-edit` | $0.09 | +#### Quality-Tier Pricing (GPT Image 2) + +`gpt-image-2` and `gpt-image-2-edit` accept an optional `quality` parameter (`low`, `medium`, `high`) that combines with `resolution` to determine price. The default tier is `high`; omitting `quality` charges the `high` rate for that resolution. See the [Generate](/api-reference/endpoint/image/generate) and [Edit](/api-reference/endpoint/image/edit) docs for usage. + +**`gpt-image-2` — Generate** + +| Resolution | low | medium | high (default) | +|---|---|---|---| +| 1K | $0.02 | $0.07 | $0.26 | +| 2K | $0.03 | $0.13 | $0.50 | +| 4K | $0.05 | $0.21 | $0.83 | + +**`gpt-image-2-edit` — Edit / Multi-Edit** + +| Resolution | low | medium | high (default) | +|---|---|---|---| +| 1K | $0.03 | $0.10 | $0.36 | +| 2K | $0.04 | $0.15 | $0.53 | +| 4K | $0.06 | $0.22 | $0.86 | + + +The Venice mobile app currently stays on the legacy fixed price (the `high`-default column rounded up by ~$0.01 at 1K and 2K) until it ships its own quality selector. Web, public API, and SDK callers always use the tier matrix above — no opt-in header required. Programmatic clients can read the same matrix at runtime from `model_spec.pricing.quality` in the [Models endpoint](/api-reference/endpoint/models/list). + + ### Audio diff --git a/swagger.yaml b/swagger.yaml index ff18fc8..486b350 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -2402,6 +2402,18 @@ components: description: 'Resolution (utilized by certain image models including Nano Banana). Examples: "1K", "2K", "4K".' example: 1K + quality: + type: string + enum: + - low + - medium + - high + description: Output quality tier. Only supported by quality-aware models + (currently `gpt-image-2`). When omitted, the model-specific default + applies (`high` for `gpt-image-2`). Combines with `resolution` to + determine pricing — see GET /api/v1/models for the full + `pricing.quality` matrix per model. + example: high enable_web_search: type: boolean description: Enable web search for the image generation task. This will allow @@ -2685,6 +2697,18 @@ components: description: Whether to use safe mode. If enabled, this will blur images that are classified as having adult content. example: false + quality: + type: string + enum: + - low + - medium + - high + description: Output quality tier. Only supported by quality-aware edit + models (currently `gpt-image-2-edit`). When omitted, the + model-specific default applies (`high` for `gpt-image-2-edit`). + Combines with `resolution` to determine pricing — see GET + /api/v1/models for the full `pricing.quality` matrix per model. + example: high required: - image - prompt @@ -2766,6 +2790,18 @@ components: description: Whether to use safe mode. If enabled, this will blur images that are classified as having adult content. example: false + quality: + type: string + enum: + - low + - medium + - high + description: Output quality tier. Only supported by quality-aware edit + models (currently `gpt-image-2-edit`). When omitted, the + model-specific default applies (`high` for `gpt-image-2-edit`). + Combines with `resolution` to determine pricing — see GET + /api/v1/models for the full `pricing.quality` matrix per model. + example: high required: - prompt - images @@ -2837,6 +2873,18 @@ components: description: Whether to use safe mode. If enabled, this will blur images that are classified as having adult content. example: false + quality: + type: string + enum: + - low + - medium + - high + description: Output quality tier. Only supported by quality-aware edit + models (currently `gpt-image-2-edit`). When omitted, the + model-specific default applies (`high` for `gpt-image-2-edit`). + Combines with `resolution` to determine pricing — see GET + /api/v1/models for the full `pricing.quality` matrix per model. + example: high required: - prompt - images From 8a09274247ebaff923c47040a354f86d5a1ed74c Mon Sep 17 00:00:00 2001 From: Dervlex Date: Fri, 22 May 2026 00:58:17 +0200 Subject: [PATCH 2/2] docs(image): drop mobile-client mention; fix incorrect "~$0.01 at 1K/2K" footnote MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit API docs are about what the API does, not which clients call it. The mobile reference also carried a quantitatively wrong claim — legacy fixed pricing is ~$0.01 above dynamic-`high` for `gpt-image-2` at *all three* resolutions (not just 1K/2K) and *identical* for `gpt-image-2-edit` at every resolution. Re-frames the four Info blocks (generate, edit, multi-edit, pricing overview) and the prose in the Models endpoint as API-and-SDK-centric, with no false claim about a specific client's bill. --- api-reference/endpoint/image/edit.mdx | 2 +- api-reference/endpoint/image/generate.mdx | 2 +- api-reference/endpoint/image/multi-edit.mdx | 2 +- api-reference/endpoint/models/list.mdx | 2 +- overview/pricing.mdx | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/api-reference/endpoint/image/edit.mdx b/api-reference/endpoint/image/edit.mdx index 8184634..587861b 100644 --- a/api-reference/endpoint/image/edit.mdx +++ b/api-reference/endpoint/image/edit.mdx @@ -30,7 +30,7 @@ Some edit models accept an optional `quality` parameter (`low`, `medium`, `high` When you omit `quality`, the model uses its default tier (`high` for `gpt-image-2-edit`). Per-tier prices (1K/2K/4K × low/medium/high) live under `model_spec.pricing.quality` in the [Models endpoint](/api-reference/endpoint/models/list) and are listed in the [Pricing overview](/overview/pricing). -**Mobile clients** stay on the legacy fixed price schedule until the mobile app ships its own quality selector. Web, public API, and SDK callers automatically use the quality-aware pricing path; no opt-in header is required. +Quality-aware pricing is the default for all API and SDK callers — no opt-in header required. Requests that omit `quality` are billed at the model's default tier (`high` for `gpt-image-2-edit`). ## Postman Collection diff --git a/api-reference/endpoint/image/generate.mdx b/api-reference/endpoint/image/generate.mdx index 25945f8..fac3cfd 100644 --- a/api-reference/endpoint/image/generate.mdx +++ b/api-reference/endpoint/image/generate.mdx @@ -76,7 +76,7 @@ Some models accept an optional `quality` parameter (`low`, `medium`, `high`) tha When you omit `quality`, the model uses its default tier (`high` for `gpt-image-2`). Pricing depends on the combination of `resolution` and `quality` — the per-tier prices for `gpt-image-2` (1K/2K/4K × low/medium/high) are exposed under `model_spec.pricing.quality` in the [Models endpoint](/api-reference/endpoint/models/list) and listed in the [Pricing overview](/overview/pricing). -**Mobile clients** are currently held back to the legacy fixed price schedule until the mobile app ships its own quality selector. Web, public API, and SDK callers automatically use the quality-aware pricing path; no opt-in header is required. +Quality-aware pricing is the default for all API and SDK callers — no opt-in header required. Requests that omit `quality` are billed at the model's default tier (`high` for `gpt-image-2`). ## Postman Collection diff --git a/api-reference/endpoint/image/multi-edit.mdx b/api-reference/endpoint/image/multi-edit.mdx index 77842de..075ef30 100644 --- a/api-reference/endpoint/image/multi-edit.mdx +++ b/api-reference/endpoint/image/multi-edit.mdx @@ -27,5 +27,5 @@ Some multi-edit models accept an optional `quality` parameter (`low`, `medium`, When you omit `quality`, the model uses its default tier (`high` for `gpt-image-2-edit`). Per-tier prices (1K/2K/4K × low/medium/high) live under `model_spec.pricing.quality` in the [Models endpoint](/api-reference/endpoint/models/list) and are listed in the [Pricing overview](/overview/pricing). -**Mobile clients** stay on the legacy fixed price schedule until the mobile app ships its own quality selector. Web, public API, and SDK callers automatically use the quality-aware pricing path; no opt-in header is required. +Quality-aware pricing is the default for all API and SDK callers — no opt-in header required. Requests that omit `quality` are billed at the model's default tier (`high` for `gpt-image-2-edit`). diff --git a/api-reference/endpoint/models/list.mdx b/api-reference/endpoint/models/list.mdx index 6ac7c79..19a971f 100644 --- a/api-reference/endpoint/models/list.mdx +++ b/api-reference/endpoint/models/list.mdx @@ -36,7 +36,7 @@ For image models that accept the optional `quality` parameter (currently `gpt-im } ``` -`pricing.resolutions` reflects the legacy per-image schedule (used when no `quality` is sent by a legacy-billed client such as the Venice mobile app). `pricing.quality` is the matrix that applies to web, public API, and SDK callers — i.e. anyone using the `quality` parameter. Both are kept in the response so clients can detect quality support and surface the matrix in their own UIs. +`pricing.resolutions` is the legacy per-image schedule kept for backward compatibility. `pricing.quality` is the per-(resolution, quality) matrix that applies whenever the `quality` parameter is supported. Both fields are kept in the response so clients can detect quality support and surface the matrix in their own UIs. ## Postman Collection For additional examples, please see this [Postman Collection](https://www.postman.com/veniceai/workspace/venice-ai-workspace/folder/38652128-59dfa959-7038-4cd8-b8ba-80cf09f2f026?action=share&source=copy-link&creator=38652128&ctx=documentation). diff --git a/overview/pricing.mdx b/overview/pricing.mdx index 783ca9a..1ec66d9 100644 --- a/overview/pricing.mdx +++ b/overview/pricing.mdx @@ -205,7 +205,7 @@ Prices per 1M tokens unless noted. All prices in USD. 1 Diem = $1/day of compute | 4K | $0.06 | $0.22 | $0.86 | -The Venice mobile app currently stays on the legacy fixed price (the `high`-default column rounded up by ~$0.01 at 1K and 2K) until it ships its own quality selector. Web, public API, and SDK callers always use the tier matrix above — no opt-in header required. Programmatic clients can read the same matrix at runtime from `model_spec.pricing.quality` in the [Models endpoint](/api-reference/endpoint/models/list). +Quality-aware pricing is the default for all API and SDK callers — no opt-in header required. Requests that omit `quality` are billed at the default tier (`high`). Programmatic clients can read the same matrix at runtime from `model_spec.pricing.quality` in the [Models endpoint](/api-reference/endpoint/models/list).