Image Models

Most image models can be called through the two OpenAI-compatible endpoints: text-to-image POST /v1/images/generations and image editing POST /v1/images/edits. Use the official OpenAI SDK and point base_url to https://api.ephone.ai/v1.

Supported parameters (sizes, quality tiers, transparent backgrounds, …) vary by model; the model detail page is authoritative. For asynchronous jobs that return image URLs, see Task API.

Text to image

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ephone.ai/v1",
    api_key="",  # replace with your API key from this site
)

result = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="An orange cat sunbathing on a windowsill, watercolor style",
    size="1024x1024",
    quality="low",
)

with open("cat.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
print(result.usage)

import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.ephone.ai/v1",
  apiKey: "", // replace with your API key from this site
});

const result = await client.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt: "An orange cat sunbathing on a windowsill, watercolor style",
  size: "1024x1024",
  quality: "low",
});

fs.writeFileSync("cat.png", Buffer.from(result.data[0].b64_json, "base64"));
console.log(result.usage);

curl https://api.ephone.ai/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "An orange cat sunbathing on a windowsill, watercolor style",
    "size": "1024x1024",
    "quality": "low"
  }'

Example response (b64_json truncated):

{
  "created": 1793011034,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }],
  "background": "opaque",
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 13,
    "input_tokens_details": { "image_tokens": 0, "text_tokens": 13 },
    "output_tokens": 196,
    "output_tokens_details": { "image_tokens": 196, "text_tokens": 0 },
    "total_tokens": 209
  }
}

Edit images

Send one or more images with a prompt to restyle, replace elements or composite several inputs; add a mask to repaint only its transparent area. Images are uploaded as a multipart form; use the field name image[] for multiple images (the official SDK handles this when you pass a list).

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ephone.ai/v1",
    api_key="",  # replace with your API key from this site
)

result = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=[open("cat.png", "rb")],
    prompt="Make the cat blue and keep everything else unchanged",
)

with open("cat-blue.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

curl https://api.ephone.ai/v1/images/edits \
  -H "Authorization: Bearer $API_KEY" \
  -F model="gpt-image-2.5-sunburst" \
  -F "image[]=@cat.png" \
  -F prompt="Make the cat blue and keep everything else unchanged"

Streaming partial images

The gpt-image family (gpt-image-2.5-sunburst, gpt-image-2.5-flare, gpt-image-2, gpt-image-1.5, gpt-image-1, …) supports streaming: pass stream: true to receive 0–3 partial images while the image is being generated, followed by the final image. Useful for showing users a rough preview early.

Parameter	Description
`stream`	Set to `true` to enable streaming
`partial_images`	Number of partial images, 0–3. With 0 only the final image is sent. When the image is generated quickly you may receive fewer partial images than requested

The response is a stream of server-sent events; each event’s type matches its event: line:

image_generation.partial_image: a partial image (image_edit.partial_image on the edit endpoint); partial_image_index starts at 0
image_generation.completed: the final image (image_edit.completed on the edit endpoint), carrying the request’s usage
error: something failed mid-stream, see below

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.ephone.ai/v1",
    api_key="",  # replace with your API key from this site
)

stream = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="An orange cat sunbathing on a windowsill, watercolor style",
    size="1024x1024",
    quality="low",
    stream=True,
    partial_images=2,
)

for event in stream:
    if event.type == "image_generation.partial_image":
        with open(f"cat-preview-{event.partial_image_index}.png", "wb") as f:
            f.write(base64.b64decode(event.b64_json))
    elif event.type == "image_generation.completed":
        with open("cat.png", "wb") as f:
            f.write(base64.b64decode(event.b64_json))
        print(event.usage)

import fs from "fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.ephone.ai/v1",
  apiKey: "", // replace with your API key from this site
});

const stream = await client.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt: "An orange cat sunbathing on a windowsill, watercolor style",
  size: "1024x1024",
  quality: "low",
  stream: true,
  partial_images: 2,
});

for await (const event of stream) {
  if (event.type === "image_generation.partial_image") {
    fs.writeFileSync(`cat-preview-${event.partial_image_index}.png`, Buffer.from(event.b64_json, "base64"));
  } else if (event.type === "image_generation.completed") {
    fs.writeFileSync("cat.png", Buffer.from(event.b64_json, "base64"));
    console.log(event.usage);
  }
}

curl -N https://api.ephone.ai/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "An orange cat sunbathing on a windowsill, watercolor style",
    "size": "1024x1024",
    "quality": "low",
    "stream": true,
    "partial_images": 2
  }'

The edit endpoint works the same way: add stream=True, partial_images=2 to client.images.edit(...) in Python, or -F stream=true -F partial_images=2 with cURL; the event names become image_edit.*. Raw event stream (b64_json truncated):

event: image_generation.partial_image
data: {"type":"image_generation.partial_image","sequence_number":0,"b64_json":"iVBORw0KGgo...","partial_image_index":0,"created_at":1793010866,"background":"opaque","output_format":"png","quality":"low","size":"1024x1024"}

event: image_generation.completed
data: {"type":"image_generation.completed","sequence_number":1,"b64_json":"iVBORw0KGgo...","created_at":1793010871,"background":"opaque","output_format":"png","quality":"low","size":"1024x1024","usage":{"input_tokens":13,"input_tokens_details":{"image_tokens":0,"text_tokens":13},"output_tokens":273,"output_tokens_details":{"image_tokens":273,"text_tokens":0},"total_tokens":286}}

Billing

Each partial image consumes some extra image output tokens (the amount depends on size and quality). They are already included in the usage of the completed event and billed at actual usage, with no separate fee. Set partial_images to 0 if you don’t need previews.
Requests that fail before the final image is delivered are not billed.
If the client disconnects mid-stream, the image is still generated and billed as usual.

Errors

Before streaming starts (invalid parameters, insufficient balance, content moderation, …): you get an HTTP error status and a JSON error body, exactly as without streaming.
During streaming (after partial images have been sent): the stream ends with an error event; the HTTP status is already 200 at that point. The official SDK raises APIError while iterating, so wrap the whole loop in try:

event: error
data: {"type":"error","error":{"message":"Image generation failed","code":"server_error"}}

Notes

Partial images are only produced for single-image requests. With n greater than 1, each final image arrives as its own completed event and usage (the total for all images) is attached to the last one.
Other models accept stream: true too: there are no partial images, and a single completed event arrives once the image is ready, so your code doesn’t need to special-case models.
When streaming, images are returned as base64 (b64_json) by default; with response_format: "url" the final image is returned as a URL, while partial images stay base64.
Without partial images the connection may be silent for a long time before the final image arrives, so set your client’s read timeout to a few minutes.

Common parameters

Parameter	Description
`model`	Model name, e.g. `gpt-image-2.5-sunburst`
`prompt`	Prompt text
`n`	Number of images; 1–10 for the gpt-image family
`size`	Size, e.g. `1024x1024`, `1536x1024`, `auto`
`quality`	Quality; `low` / `medium` / `high` / `auto` for the gpt-image family, plus `xhigh` / `max` on the 2.5 models
`background`	`auto` / `opaque` / `transparent` (transparent requires `png` or `webp`)
`output_format`	`png` / `jpeg` / `webp`
`output_compression`	Compression 0–100, only for `jpeg` / `webp`
`moderation`	Moderation strictness: `auto` / `low`
`response_format`	`b64_json` or `url`. The gpt-image family defaults to `b64_json`; with `url` you get an image link hosted by this site
`stream` / `partial_images`	Streaming and number of partial images, see above
`user`	An identifier for your end user, used for abuse monitoring; optional

Notes

Set OPENAI_BASE_URL to https://api.ephone.ai/v1
Set OPENAI_API_KEY to your API key
Most models support the OpenAI image endpoints; for the few that don’t, see the model documentation
Image URLs (from response_format: "url" or the task API) expire, so download and keep them promptly

OpenAI image generation guide

Official usage guide, including streaming and editing

OpenAI Images API reference

Full parameters and event fields

Getting Started

Models & Services

Usage Guide

Text to image

Edit images

Streaming partial images

Billing

Errors

Notes

Common parameters

Notes

OpenAI image generation guide

OpenAI Images API reference

​Text to image

​Edit images

​Streaming partial images

​Billing

​Errors

​Notes

​Common parameters

​Notes

​Related links

OpenAI image generation guide

OpenAI Images API reference

Text to image

Edit images

Streaming partial images

Billing

Errors

Notes

Common parameters

Notes

Related links