Skip to main content

Images

Image models generate an image from a prompt and, most of them, edit an image or draw from reference images. Both follow OpenAI's Images API, so client.images.generate() and client.images.edit() in the OpenAI SDKs work with the base URL changed.

The two samples below are files we run against the service before publishing.

Generate​

# Generate an image. The response carries a URL you can download from.
curl -sS "${OCEANTOKEN_BASE_URL:-https://api.oceantoken.ai/v1}/images/generations" \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A small lighthouse on a calm sea at dawn, watercolor",
    "size": "1024x1024",
    "n": 1
  }'
FieldWhat it does
modelAn image model's ID.
promptWhat to draw.
sizeWidth x height, such as 1024x1024 or 1536x1024.
qualitylow, medium or high on models that have quality levels. Lower is faster and cheaper.
nHow many images, on models that make more than one per request.

A value the model does not take is refused with 400 invalid_request, and the message lists the values it does take. To read them first, see A model's options.

The response​

{
  "created": 1792000000,
  "data": [{"url": "https://..."}]
}

Each image comes back as a URL in data[].url, also when you ask for b64_json. Download it within 24 hours: the URL stops working after that (Limits → Retention). The images also appear in the console under Media.

Edit an image, or draw from references​

Send the image the model should start from. As JSON, give its URL or a data URL in images:

# Edit an image, or generate from reference images: send the image's URL (or a
# data URL) in `images`. The response carries a URL for each result.
curl -sS --fail-with-body "${OCEANTOKEN_BASE_URL:-https://api.oceantoken.ai/v1}/images/edits" \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || date +%s%N)" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "Turn this logo into a glossy blue enamel pin on a white background",
    "images": ["https://docs.oceantoken.ai/img/oceantoken-mark-512.png"],
    "size": "1024x1024",
    "quality": "low"
  }'

Or upload the file, as OpenAI's SDKs and the edit form do:

curl https://api.oceantoken.ai/v1/images/edits \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY" \
  -F model="openai/gpt-image-2" \
  -F image=@product.png \
  -F prompt="Place this product on a marble kitchen counter, soft morning light"
  • Several reference images, for example a person and a garment, go in the same list (or as repeated image fields). Each model takes up to a set number, listed in its options; more is refused with 400, never silently cut.
  • A mask (mask, one PNG whose transparent area marks what to change) works on models that support masks. On a model that does not, the request is refused rather than run without it.
  • Reference images also work on /v1/images/generations: the request is treated as an edit.
  • URLs must be public. Each image may be up to 25 MB, but the whole request is at most 10 MB, so send large images as URLs (Limits).

A model's options​

The sizes, quality levels, number of images and number of reference images a model takes:

curl "https://api.oceantoken.ai/oceantoken/image/model-spec?model=openai/gpt-image-2" \
  -H "Authorization: Bearer $OCEANTOKEN_API_KEY"

The answer's spec has aspectRatios, resolutions, qualities, maxImages (the most n can be) and maxReferences (the most reference images).

Retry without paying twice​

An image is charged when it is made. Send an Idempotency-Key header with a unique value on every request: if you retry after a timeout with the same key and body, you get the first result back instead of a second, charged, image. See Errors → Retrying a request that costs money.

Cost​

Image models are charged per image, per megapixel or per token, depending on the model; see How you are charged. Each response carries what it cost in the x-oceantoken-cost header, and Logs in the console lists every request. Prices are on each model's page on oceantoken.ai.

Next​