Skip to main content

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 the base_url and api_key.
The SDK sends your key as an Authorization: Bearer header, which the Nunchux API accepts on every endpoint. See Authentication for details.

Text-to-Image

Generate images from text descriptions using client.images.generate(). Nunchux-specific parameters like tier and seed are passed via extra_body.

Image-to-Image

Edit and transform existing images using client.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 the extra_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_value
integer
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:
  1. n must be 1. One image per request. Any other value returns 400. Send concurrent requests to generate a batch.
  2. Errors do not use the OpenAI error shape. See Error Handling below.

Error Handling

Two error shapes are in use. Most endpoints return detail and request_id. Migrated endpoints add a catalog envelope under error.
On /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:
Neither shape carries OpenAI’s 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.

Supported models

Every Nunchux Optimized image model works with the OpenAI SDK. See the models table for the model IDs, and Text-to-image and Image-to-image for every request field.