Images

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

POST /v1/images/generations creates images from a text prompt. It keeps the OpenAI-shaped request while adding URL-based image references and native batch generation for ModelArk models.

POST/v1/images/generations

Connecting#

With the OpenAI SDK, set base_url to https://apirouter.pleum.ai/v1. The SDK appends /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	Optional	Image model ID. Defaults to `dall-e-3`.
prompt	string	Required	Text describing the image to create. Up to 4,000 characters.
n	integer	Optional	Requested image count. 1–15, default 1. Whether batching is accepted is model-specific.
size	string \| null	Optional	Output size. Omit it to use the selected provider's default. See the ModelArk preset and pixel limits below.
image	string \| null	Optional	`images[0]` compatibility alias for one input-image URL. Only HTTP(S) URLs are accepted.
images	string[]	Optional	Ordered input-image URLs. Combined with the image alias, deduplicated, and limited to 14 references.
response_format	string \| null	Optional	For example url or b64_json. Supported values depend on the selected model/provider.
charge_amount_krw	integer \| null	Optional	Fixed KRW settlement amount. Not available to normal API keys; only first-party delegated keys may use it.

request

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"
  }'

BytePlus ModelArk limits#

ModelArk reference, size, and batch limits are checked before a credit hold. Unsupported counts, sizes, or n values return 400 without a charge.

Parameter	Type	Required	Description
Seedream 5 / 4.5 / 4.0	reference + batch	Optional	Up to 14 references each. Only these Seedream families support native n=1–15 batching; references plus outputs must also total no more than 15.
Dola Seedream 5 Pro	reference	Optional	Up to 10 references and one output per request. Its price variant can depend on whether the returned size crosses 2.36MP.
SeedEdit 3.0 / Seedream 3.0 T2I	reference	Optional	SeedEdit 3.0 accepts one reference. Seedream 3.0 T2I is text-to-image only and accepts no references.
size presets	string	Optional	Seedream 5: 2k/3k/4k; Seedream 4.5: 2k/4k; Seedream 4.0: 1k/2k/4k. When omitted, these models use ModelArk's 2048×2048 default.
explicit WxH	string	Optional	Those Seedream models also accept <width>x<height> instead of a preset: 3,686,400–16,777,216 total pixels and an aspect ratio from 1:16 to 16:1.

Idempotency-Key is optional and limited to 128 characters. The same key and body replay the stored response for 24 hours; using the same key with a different body returns 422.

Response#

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

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.04, "krw": 55, "fx_rate": 1525.0, "markup_rate": 0.0}
}

Billing#

Billing uses the number of outputs that actually succeeded and the ModelArk-returned output-size/reference variant. A partial batch does not settle failed images.

Provider image URLs can expire. Save them yourself if you need retention, or request b64_json when the selected model supports it.

Image edits#

POST/v1/images/edits

POST /v1/images/edits edits an image via multipart upload. Only OpenAI gpt-image-* models are supported; use generations for SeedEdit URL i2i.

Parameter	Type	Required	Description
image	file	Required	Source image file to edit.
prompt	string	Required	Edit instruction text.
mask	file	Optional	Optional mask marking the editable region.
model	string	Optional	Defaults to `gpt-image-2`.
n / size / response_format	optional	Optional	Same optional fields as OpenAI Images edits.

request

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"

Unsupported models are rejected before hold. The response shape matches generations.