OpenAI Compatibility
Use the OpenAI SDK with the Nunchux API
Overview
The Nunchux API is compatible with the OpenAI Python SDK. Point the client at the Nunchux base URL and use your Nunchux API key. Your existing OpenAI code keeps working.Installation
Install the OpenAI Python SDK:Client Setup
Point the OpenAI client at the Nunchux API by setting thebase_url and api_key.
Authorization: Bearer header, which the Nunchux API accepts on every endpoint. See Authentication for details.
Text-to-Image
Generate images from text descriptions usingclient.images.generate(). Nunchux-specific parameters like tier and seed are passed via extra_body.
Image-to-Image
Edit and transform existing images usingclient.images.edit(). Pass the source image as a file object opened in binary mode.
Nunchux-Specific Parameters
The OpenAI SDK does not natively support all Nunchux parameters. Use theextra_body argument to pass Nunchux-specific fields.
string
Performance tier controlling the tradeoff between speed and cost. See Performance Tiers for details.Options:
radical_speed, radical_valueinteger
Random seed for reproducible generation. Use the same seed with identical
parameters for consistent results.
integer
Output width in pixels. Send it together with
height. The two fields take
precedence over the standard size argument. Models priced per megapixel
require width and height, or size. Range: 1-8192.integer
Output height in pixels. Send it together with
width. Models priced per
megapixel require width and height, or size. Range: 1-8192.SizingThe examples on this page use
size because it is the standard OpenAI argument and it works. Elsewhere in these docs you will see width and height, which are the preferred spelling. The API accepts either form and resolves both to the same dimensions. Pass them through extra_body if you want to match the rest of the platform.Models priced per megapixel need dimensions. The pricing page shows each model’s unit. Today, every image model except Ideogram 4 is priced per megapixel. The OpenAI SDK sends no size unless you set it. On a per-megapixel model, a request with neither size nor width and height returns a 400.Using Other SDK Format
Nothing about the API is Python-specific. The official OpenAI Node SDK works against the same base URL and the same key.TypeScriptTypeScript refuses undeclared properties in an object literal, but applies that check only to literals. Assign the parameters to a variable first. This rule is TypeScript excess property checking, not an API limit. See the TypeScript handbook for the full rule.
Limitations
The API speaks the OpenAI image shape, but it is not OpenAI. Two differences matter when you port existing code:nmust be 1. One image per request. Any other value returns400. Send concurrent requests to generate a batch.- Errors do not use the OpenAI error shape. See Error Handling below.
Error Handling
Two error shapes are in use. Most endpoints returndetail and request_id. Migrated endpoints add a catalog envelope under error.
/v1/images/generations, a non-integer n also returns HTTP 400 with a plain detail string. The message text depends on the model. This example is from a per-megapixel model:
type or param, so .type and .param on the raised exception are always None. Branch on the HTTP status code, not on the error body. request_id is present on both shapes. Quote it when you contact support. It is how we find your request. See Errors for the full code catalog.