Capabilities

Images

Send image inputs, generate images, and translate multipart image edits safely.

On this page

This page is for developers adding vision input, image generation, or prompt-based image edits.

Image input in chat#

For a model whose input modalities include images, send an HTTPS URL or a base64 data URL in an image_url content part.

BashSyntax highlighted

curl https://api.clssai.com/v1/chat/completions \
  -H "Authorization: Bearer $CLSSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"google/gemini-2.5-flash",
    "messages":[{"role":"user","content":[
      {"type":"text","text":"Describe the image."},
      {"type":"image_url","image_url":{"url":"https://example.com/image.png"}}
    ]}]
  }'

Generate an image#

POST /v1/images accepts JSON and returns image data from the upstream API. The primary response form is data[].b64_json.

BashSyntax highlighted

curl https://api.clssai.com/v1/images \
  -H "Authorization: Bearer $CLSSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-image-1","prompt":"A small red cabin under a clear night sky","n":1,"size":"1024x1024"}'

At the measured directory price, this 1024×1024 example costs approximately $0.17 per image. Check the current reference price on Models & pricing before running it.

PythonSyntax highlighted

import base64
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.clssai.com/v1", api_key=os.environ["CLSSAI_API_KEY"])
result = client.images.generate(
    model="openai/gpt-image-1",
    prompt="A small red cabin under a clear night sky",
    size="1024x1024",
)
with open("cabin.png", "wb") as output:
    output.write(base64.b64decode(result.data[0].b64_json))

JavaScriptSyntax highlighted

import { writeFile } from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.clssai.com/v1",
  apiKey: process.env.CLSSAI_API_KEY,
});
const result = await client.images.generate({
  model: "openai/gpt-image-1",
  prompt: "A small red cabin under a clear night sky",
  size: "1024x1024",
});
await writeFile("cabin.png", Buffer.from(result.data[0].b64_json, "base64"));

Supported dimensions and output characteristics depend on the selected model. Inspect model metadata and handle an upstream 4xx when a model rejects a field.

Edit images#

The edit endpoint requires multipart form data with model, a non-empty prompt, and at least one image or image[] file. All image files together must be no more than 8 MB; larger uploads return 413.

BashSyntax highlighted

curl https://api.clssai.com/v1/images/edits \
  -H "Authorization: Bearer $CLSSAI_API_KEY" \
  -F "model=openai/gpt-image-1" \
  -F "prompt=Replace the background with a clear night sky" \
  -F "image=@input.png" \
  -F "size=1024x1024"

Masked edits are rejected. Describe the edit in the prompt instead. The response_format form field is ignored; edits return b64_json.

Common mistakes#

Do not send a mask field to image edits.
Do not depend on response_format for edits; decode b64_json.
Keep edit image files within the combined 8 MB limit.
Use the complete image model ID and preserve any :free or :batch suffix.
Include /v1 in OpenAI SDK base URLs, omit /v1 from the Anthropic SDK base URL, and call from a server.
Check empty streaming choices arrays and use cf-ray when tracing inference.

Also available (pass-through, lightly tested)#

Video creation and job retrieval are passed through under /v1/videos. Treat the returned job schema as upstream-defined.

BashSyntax highlighted

curl https://api.clssai.com/v1/videos \
  -H "Authorization: Bearer $CLSSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"black-forest-labs/flux-3-video","prompt":"A paper boat crossing a quiet pond"}'

Need a hand?

Find answers to common questions or diagnose a failed request.

Frequently asked questions →Troubleshoot errors →