Skip to main content

Documentation

OpenAI compatibility

Use the OpenAI client library

Image generation works with the OpenAI libraries when you change the base URL and the key:

from openai import OpenAI

client = OpenAI(base_url="https://api.cheapvids.com/v1", api_key="cv_live_YOUR_KEY")
image = client.images.generate(model="gpt-image-2.5", prompt="A lighthouse at dusk", size="1024x1024")
print(image.data[0].url)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.cheapvids.com/v1", apiKey: "cv_live_YOUR_KEY" });
const image = await client.images.generate({ model: "gpt-image-2.5", prompt: "A lighthouse at dusk", size: "1024x1024" });
console.log(image.data[0].url);

What is supported

Only POST /v1/images/generations. There is no images/edits or images/variations, and no chat, text or video endpoint on the compatible surface (use POST /v1/generations for video).

FieldBehavior
modelRequired. An image model id from GET /v1/models. A video model returns 422.
promptRequired.
nMust be 1 or omitted; any other value returns 422 ("n must be 1; send separate requests").
size1024x1024, 1536x1024, 1792x1024, 1024x1536, 1024x1792 or auto. Mapped to the closest aspect ratio the model supports: square becomes 1:1, wide 16:9, tall 9:16; auto uses the model default.
qualityhd selects 2k resolution when the model supports it; other values are ignored.
response_formaturl (default) or b64_json.
userIgnored.
planCheapVids extension, see below. Unknown fields are ignored.

Choosing the plan group

plan can be sent in the body or in the X-Plan header (when both are present they must agree, otherwise 422).

  • A model that is not in Studio (for example gpt-image-2.5) without plan uses credits.
  • A model that exists in both groups (for example nano-banana-2) without plan returns 400 plan_required ("This model is available in Studio and Credits; set plan or X-Plan"). The system never guesses the group.

With the OpenAI libraries you can pass plan through extra_body={"plan": "studio"} (Python) or extra_headers (X-Plan).

Response

The request waits for the image, up to 90 seconds. On success:

{ "created": 1760000000, "data": [{ "url": "https://api.cheapvids.com/v1/generations/0190.../content?exp=...&sig=..." }] }
  • url is a CheapVids URL (valid one hour, and the result stays downloadable for the download window, see Generations). With response_format: "b64_json" the image is returned as b64_json (up to 20 MiB; larger images or a source error fall back to url).
  • If the image is not ready after 90 seconds the answer is 504 with code generation_pending and details.generation_id. The job keeps running: read it with GET /v1/generations/{id}.
  • A failed job returns the error of the job (for example content_policy_violation) and is refunded.

Retries do not double charge

OpenAI libraries retry on 5xx and timeouts with the same body. Because an identical request within 120 seconds returns the original job (Idempotency), a retry after 504 finds the same job and charges nothing more. For the SDKs and other calls use the native endpoints.