Image Generation API
ShenwenAI exposes an OpenAI Images API aligned with the official Sub2API contract. Clients that already support Sub2API Images normally only need a new Base URL and dedicated image API key.
Select gpt-image-2 in an Images or painting feature. Do not send this model to Chat Completions. Image keys show a 1x rate and settle from the cost returned by Main Sub2API.
Copy these model IDs into config files, API request bodies, or any OpenAI-compatible client that asks for a model name.
Prepare your API key first
1. Go to your account page
After logging in, create or copy an API key from your account page. It looks like sk-or-v1-xxxxxxxxxxxx. Treat it like a password.
Go to account page2. Create an API key and choose a channel
Select Create API Key, enter a recognizable name, then choose the channel that fits your use case:
- Stable · 0.22x (Pro pool)
- Prioritizes stability for OpenAI (Codex), OpenAI-compatible clients, and Claude Code. Recommended for long-running or important text workloads.
- Economy · 0.09x (Plus pool)
- Prioritizes price for OpenAI (Codex) and OpenAI-compatible clients. Recommended for everyday development, learning, testing, and cost-sensitive text workloads.
For images, create a separate OpenAI image key or Grok image key. Text and image purposes cannot be mixed in one key.
3. Confirm the Base URL
Use the Base URL with /v1. The generation endpoint is /v1/images/generations.
Do not share your API key with others or commit it to GitHub, GitLab, or any public repository.
The commands below will switch based on your selected system.
Configure Cherry Studio
Add an OpenAI or OpenAI-compatible provider. Set the API URL to https://api.shenwenai.com/v1 and enter the API key created in your ShenwenAI account.
Add gpt-image-2 as a custom image model, then select it from Cherry Studio's painting or image-generation screen. A regular chat screen does not call the Images API.
If model discovery does not add it automatically, enter the model ID gpt-image-2 manually.
Check model discovery
curl https://api.shenwenai.com/v1/models \
-H "Authorization: Bearer sk-or-v1-your-key"Generate one image
This example requests a temporary URL for convenient manual testing. Omit response_format to receive the standard b64_json response.
Reuse the same Idempotency-Key only when retrying the same request. Use a new value after changing the prompt or options.
curl https://api.shenwenai.com/v1/images/generations \
-H "Authorization: Bearer sk-or-v1-your-key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: my-first-image-001" \
-d '{
"model": "gpt-image-2",
"prompt": "A premium pour-over coffee beside a window, realistic photography",
"n": 1,
"size": "1536x1024",
"quality": "medium",
"output_format": "png",
"response_format": "url"
}'Edit with reference images
Upload up to ten PNG, JPEG, or WebP reference images, with a maximum of 10MB each and 64MB for the complete request.
curl https://api.shenwenai.com/v1/images/edits \
-H "Authorization: Bearer sk-or-v1-your-key" \
-H "Idempotency-Key: my-first-edit-001" \
-F "model=gpt-image-2" \
-F "image[]=@reference.png" \
-F "prompt=Keep the subject and replace the background with snowy mountains" \
-F "size=1024x1024" \
-F "quality=high"Python OpenAI SDK
from openai import OpenAI
import base64
client = OpenAI(
api_key="sk-or-v1-your-key",
base_url="https://api.shenwenai.com/v1",
)
result = client.images.generate(
model="gpt-image-2",
prompt="Minimal product photography of a smart watch",
size="1024x1024",
quality="medium",
)
with open("shenwen-image.png", "wb") as image_file:
image_file.write(base64.b64decode(result.data[0].b64_json))Parameters and billing
Supported fields include model, prompt, n, size, quality, background, output_format, output_compression, moderation, partial_images, stream, response_format, and user. Edits additionally accept image / image[] and mask. Unknown future fields continue through to Sub2API.
GPT Image 2 accepts auto or WIDTHxHEIGHT when both edges are multiples of 16, the longest edge is at most 3840, total pixels are 655,360 to 8,294,400, and the aspect ratio is at most 3:1. Common sizes include 1024x1024, 1536x1024, 1024x1536, 2048x2048, 2048x1152, and 3840x2160.
Image keys show a 1x rate. Default always uses medium and High always uses high. With ¥1 = $1 platform credit, the wallet charge equals the cost returned by Main Sub2API. n accepts 1 through 5.
The website tool and public API share a 30-image generation pool. One user and one key may each generate at most five images concurrently. Requests hold their connection and queue after a limit is reached; queued requests are not sent upstream or charged. A 429 is returned only when a queue limit or the 15-minute wait limit is reached.
The key tier overrides the request quality. Older clients may still send standard / hd, and jpg normalizes to jpeg. GPT Image 2 always uses high input fidelity and does not support transparent backgrounds; style, input_fidelity, and transparent-background requests are safely ignored and listed in the X-Shenwen-Image-Compatibility response header.
2K and 4K are requested targets, not guarantees. Outputs above 2560x1440 total pixels are experimental and the provider may return smaller dimensions. Inspect the downloaded image for its actual pixel size. Complex requests can exceed two minutes; api.shenwenai.com allows up to 15 minutes.
The service reserves credit from the requested size, quality, and n, then settles from Main Sub2API cost. Failed requests without cost or usage release the reservation.
Top-ups convert ¥1 into $1 platform credit, and image generation is charged at the actual Main Sub2API cost (1x).
Troubleshooting
gpt-image-2 is missing from /models: image generation has not been enabled for this API key.
400 / model_not_found: use the exact gpt-image-2 model ID on an Images endpoint, not Chat Completions.
Requests sent to shenwenai.com/v1: change the Base URL to https://api.shenwenai.com/v1. The website hostname is not the API hostname.
A request is still generating after about 120 seconds: 120 seconds is a renewable concurrency lease, not the request timeout. Keep the connection open and configure a client timeout above two minutes.
409 / idempotency_key_in_use: use a new Idempotency-Key for changed parameters.
429 / image_queue_full, image_user_queue_full, or image_queue_timeout: the global queue, personal queue, or 15-minute wait limit was reached. Try again later.
402 / insufficient_quota: top up enough balance for the request reservation.