Images

OpenAI-compatible image generation and editing, plus BytePlus ModelArk multi-reference and batch image generation.

POST /v1/images/generations creates a new image from a text prompt. To modify an existing image, use the image edits section below.

POST/v1/images/generationsHost: apirouter.pleum.aiAuth: API key

Quickstart#

Set the key in the PLEUM_API_KEY environment variable, then run the example as written.

terminal

Send the request from a terminal with curl.

export PLEUM_API_KEY=plm_xxxxxxxxxxxxxxxx

curl https://apirouter.pleum.ai/v1/images/generations \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-260128",
    "prompt": "A red panda coding at a tiny laptop, watercolor style",
    "response_format": "url"
  }'

Send the request with the OpenAI Python SDK.

import os

from openai import OpenAI

# Read the key from the PLEUM_API_KEY environment variable.
client = OpenAI(
    api_key=os.environ["PLEUM_API_KEY"],
    base_url="https://apirouter.pleum.ai/v1",
)

result = client.images.generate(
    model="seedream-5-0-260128",
    prompt="A red panda coding at a tiny laptop, watercolor style",
    response_format="url",
)
print(result.data[0].url)

Send the request with the OpenAI Node.js SDK.

import OpenAI from "openai";

// Read the key from the PLEUM_API_KEY environment variable.
const client = new OpenAI({
  apiKey: process.env.PLEUM_API_KEY,
  baseURL: "https://apirouter.pleum.ai/v1",
});

async function main() {
  const result = await client.images.generate({
    model: "seedream-5-0-260128",
    prompt: "A red panda coding at a tiny laptop, watercolor style",
    response_format: "url",
  });
  console.log(result.data?.[0]?.url);
}

main();

Connecting#

With the OpenAI SDK, set base_url to https://apirouter.pleum.ai/v1. The SDK appends /images/generations to it. The final request path is /v1/images/generations.

image-ai-sdk.ts

OpenAI Images generations API

import { generateImage } from "ai";
import { createPleum } from "pleumrouter-ai-sdk-provider";

const pleum = createPleum({
  apiKey: "plm_xxxxxxxxxxxxxxxx",
});

const result = await generateImage({
  model: pleum.imageModel("seedream-5-0-260128"),
  prompt: "A red panda coding at a tiny laptop, watercolor style",
});

console.log(result.image);

OpenAI Images generations API

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "plm_xxxxxxxxxxxxxxxx",
  baseURL: "https://apirouter.pleum.ai/v1",
});

const response = await openai.images.generate({
  model: "seedream-5-0-260128",
  prompt: "A red panda coding at a tiny laptop, watercolor style",
});

console.log(response.data[0].url);

OpenAI Images generations API

from openai import OpenAI

client = OpenAI(
    api_key="plm_xxxxxxxxxxxxxxxx",
    base_url="https://apirouter.pleum.ai/v1",
)

response = client.images.generate(
    model="seedream-5-0-260128",
    prompt="A red panda coding at a tiny laptop, watercolor style",
    response_format="b64_json",
)

print(response.data[0].b64_json[:80], "...")

OpenAI Images generations API

curl https://apirouter.pleum.ai/v1/images/generations \
  -H "Authorization: Bearer plm_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-260128",
    "prompt": "A red panda coding at a tiny laptop, watercolor style",
    "response_format": "b64_json"
  }'

OpenAI Images generations API

curl https://apirouter.pleum.ai/v1/images/edits \
  -H "Authorization: Bearer plm_xxxxxxxxxxxxxxxx" \
  -F "model=gpt-image-2" \
  -F "prompt=Add a red hat" \
  -F "image=@./source.png"

Request body#

Parameter	Type	Required	Description
model	string	Required	Image model ID. Set it on every request; a request that omits `model` returns `422`.
prompt	string	Required	Text that describes the image. Up to 4,000 characters.
n	integer	Optional	Number of images to generate. Default 1. Values of 2 or more are accepted only by Seedream 5 / 4.5 / 4.0 (up to 15); every other model accepts 1 only.
size	string \| null	Optional	Output size. Seedream 5 / 4.5 / 4.0 accept only the lowercase presets in the table below. When omitted, Seedream models use 2048x2048 and every other model uses 1024x1024.
image	string \| null	Optional	A single input-image URL. It is used as the first reference image and accepts only HTTP(S) URLs.
images	string[]	Optional	Ordered input-image URLs. Combined with image, deduplicated, and limited to 14 references.
response_format	string \| null	Optional	url or b64_json. When omitted, a model may return either url or b64_json. Gemini image models always return b64_json, whatever the value.

request

export PLEUM_API_KEY=plm_xxxxxxxxxxxxxxxx

curl https://apirouter.pleum.ai/v1/images/generations \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-mug-001" \
  -d '{
    "model": "seedream-5-0-260128",
    "prompt": "A red panda coding at a tiny laptop, watercolor style",
    "images": ["https://example.com/style-reference.png"],
    "n": 2,
    "size": "2k",
    "response_format": "url"
  }'

Idempotency-Key is optional. It accepts up to 128 characters. A request with the same key and body replays the stored response for 24 hours. Reusing the key with a different body returns 422. A request that is still processing within 10 minutes returns 409.

BytePlus ModelArk limits#

ModelArk reference count, size, and n limits are checked before the credit hold. A request that exceeds a limit returns 400 without a charge.

Parameter	Type	Required	Description
Seedream 5 / 4.5 / 4.0	reference + batch	Optional	Up to 14 references per model. Only this family supports batch output with n=1–15. References plus outputs must total 15 or fewer.
Dola Seedream 5 Pro	reference	Optional	Up to 10 references and one output per request. The price tier depends on whether the returned output size exceeds 2.36MP.
size presets	string	Optional	Seedream 5 accepts 2k, 3k, and 4k. Seedream 4.5 accepts 2k and 4k. Seedream 4.0 accepts 1k, 2k, and 4k. Send presets in lowercase; uppercase values and width-by-height values such as 2048x2048 return 400.

Response#

The response contains an OpenAI-shaped data array. Each item has url or b64_json. A ModelArk item can include size. cost is a PleumRouter field.

200 OK

{
  "created": 1719446400,
  "data": [
    {
      "url": "https://.../img.png",
      "revised_prompt": "A red panda coding at a tiny laptop, watercolor style",
      "size": "2048x2048"
    }
  ],
  "model": "seedream-5-0-260128",
  "cost": {"usd": 0.035, "krw": 47.0, "fx_rate": 1342.48, "markup_rate": 0.0}
}

Parameter	Type	Required	Description
created	integer	Required	Creation time as a Unix timestamp in seconds.
data	array	Required	Array of image items. For ModelArk, only successful items are included.
data[].url	string	Optional	Image URL, returned when response_format is url.
data[].b64_json	string	Optional	Base64-encoded image data, returned when response_format is b64_json.
data[].revised_prompt	string	Optional	Prompt revised by the provider. Included only when the provider returns it.
data[].size	string	Optional	Output size returned by ModelArk, for example 2048x2048.
model	string	Required	Model ID used for the request.
cost	object	Optional	Cost details. It may be omitted when settlement is late. See Where to find cost.
cost.usd	number	Optional	Cost in USD.
cost.krw	number	Optional	Cost in KRW.
cost.fx_rate	number	Optional	Applied exchange rate, rounded to two decimal places.
cost.markup_rate	number	Optional	Applied markup rate.

Errors#

Status

Cause

Action

400

The reference count, size, or n exceeds the limit for a ModelArk model.

Lower the value to within the limit. No charge applies.

400

image or images was sent to a model that does not accept reference images. Only Seedream 5 / 4.5 / 4.0 (up to 14) and Dola Seedream 5 Pro (up to 10) accept reference images.

Remove image and images, then send the request again.

400

The model does not support the n you sent. Models other than Seedream 5 / 4.5 / 4.0 accept n=1 only.

Set n to 1.

409

A request with the same Idempotency-Key is still processing within 10 minutes.

Wait, then send the same body with the same key.

422

The same Idempotency-Key was used with a different request body.

Use a new key, or send the same body as before.

422

The body breaks a schema limit: prompt is over 4,000 characters, n is outside 1–15, there are more than 14 references, or an image URL is not HTTP(S).

Bring the values within the limits and send the request again.

For other error codes, see the error code list.

Billing and limits#

The billing unit follows the price_unit of the model (per image or per token). Dola Seedream 5 Pro also prices by output-size tier and from the second reference image. If only part of a batch succeeds, the failed images are not charged.

The image URLs in a url response are provided by the provider. If you need to keep an image, save it yourself after you receive the response, or request b64_json when the model supports it.

Image edits#

POST/v1/images/editsHost: apirouter.pleum.aiAuth: API key

POST /v1/images/edits edits an existing image with a multipart request. Editing supports only models whose operations in the GET /v1/models response include image.edit, and the example uses gpt-image-2.

Parameter	Type	Required	Default	Description
image	file	Required		Source image file to edit. Accepts JPEG, PNG, or WebP files up to 25MB.
prompt	string	Required		Edit instruction text.
mask	file	Optional		Optional mask image. The format and size limits are the same as for image.
model	string	Optional	gpt-image-2	Model ID for the edit.
n	integer	Optional	1	Number of images to generate. Currently only 1 is accepted.
size	string \| null	Optional		Output size. When omitted, the provider's default size is used.
response_format	string \| null	Optional		For example url or b64_json.

request

export PLEUM_API_KEY=plm_xxxxxxxxxxxxxxxx

curl https://apirouter.pleum.ai/v1/images/edits \
  -H "Authorization: Bearer $PLEUM_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Add a red hat to the subject" \
  -F "image=@./source.png"

Status

Cause

Action

400

The image file is missing or empty, or the mask file is empty.

Check the files and send them again.

400

The model does not support the n you sent. Editing accepts n=1 only.

Set n to 1.

413

The image or mask file is larger than 25MB.

Reduce the file size to 25MB or less.

415

The Content-Type of the image or mask part is not image/jpeg, image/png, or image/webp.

Set the Content-Type of the part and send it again. With curl, append it to the -F value, for example ;type=image/webp.

422

n is outside the range 1–10.

Set n to 1.

The edit response has the same shape as the generations response. Billing counts output images.

Next steps#

For other media generation APIs, see Video generation, Audio, and 3D generation.