Images

OpenAI 호환 이미지 생성·편집과 BytePlus ModelArk의 다중 reference·배치 이미지 생성을 제공합니다.

POST /v1/images/generations는 텍스트 프롬프트로 이미지를 생성합니다. 기존 OpenAI 형식은 유지하면서 ModelArk 모델에는 URL 기반의 이미지 reference와 네이티브 배치 생성을 제공합니다.

POST/v1/images/generations

연결하기#

OpenAI SDK로 연결할 때 base_url을 https://apirouter.pleum.ai/v1로 설정하세요. SDK가 /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"

요청 본문#

파라미터	타입	필수	설명
model	string	선택	이미지 모델 ID. 기본값 `dall-e-3`입니다.
prompt	string	필수	생성할 이미지를 설명하는 텍스트. 최대 4,000자.
n	integer	선택	요청 이미지 수. 1~15, 기본값 1. 실제 배치 허용 여부는 모델별입니다.
size	string \| null	선택	출력 크기. 생략하면 선택한 provider의 기본값을 사용합니다. ModelArk 지원 모델의 preset/화소 제한은 아래 표를 확인하세요.
image	string \| null	선택	기존 단일 입력 이미지 URL. `images[0]`의 별칭이며 HTTP(S) URL만 허용합니다.
images	string[]	선택	순서가 있는 입력 이미지 URL 목록. image 별칭을 합친 뒤 중복을 제거해 최대 14개입니다.
response_format	string \| null	선택	예: url 또는 b64_json. 실제 지원값은 선택한 모델/provider에 따라 달라집니다.
charge_amount_krw	integer \| null	선택	고정 KRW 정산 금액. 일반 API 키는 사용할 수 없고, 1st-party 위임 키만 허용됩니다.

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 제한#

ModelArk의 reference·size·batch 제한은 크레딧 hold 전에 검증됩니다. 지원하지 않는 reference 수, size 또는 n은 결제 없이 400으로 거절됩니다.

파라미터	타입	필수	설명
Seedream 5 / 4.5 / 4.0	reference + batch	선택	각각 최대 14개 reference. Seedream 5/4.5/4.0 계열만 n=1~15의 네이티브 batch를 지원하며 reference+출력 합계도 15 이하여야 합니다.
Dola Seedream 5 Pro	reference	선택	최대 10개 reference, 요청당 출력 1장입니다. 응답의 실제 size가 2.36MP 경계를 넘는지에 따라 가격 variant가 달라질 수 있습니다.
SeedEdit 3.0 / Seedream 3.0 T2I	reference	선택	SeedEdit 3.0은 reference 1개만 지원합니다. Seedream 3.0 T2I는 text-to-image 전용이므로 reference를 받을 수 없습니다.
size presets	string	선택	Seedream 5: 2k/3k/4k, Seedream 4.5: 2k/4k, Seedream 4.0: 1k/2k/4k. 이 모델들은 size 생략 시 ModelArk 기본 2048×2048을 사용합니다.
explicit WxH	string	선택	위 Seedream 모델은 preset 대신 <width>x<height>를 쓸 수 있습니다. 총 3,686,400~16,777,216px, 비율 1:16~16:1이어야 합니다.

Idempotency-Key 헤더는 선택 사항이며 최대 128자입니다. 같은 키와 같은 본문은 24시간 동안 저장된 응답을 재생합니다. 같은 키에 다른 본문은 422입니다.

응답#

응답은 OpenAI 형식의 data 배열을 반환합니다. 각 성공 항목에는 url 또는 b64_json가 있으며, ModelArk 응답에는 size가 포함될 수 있습니다. cost는 PleumRouter 확장입니다.

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

과금 방식#

과금은 실제로 성공한 출력 이미지 수와 ModelArk가 반환한 출력 size/reference variant를 기준으로 합니다. 부분 성공 batch는 실패한 이미지에 대해 정산하지 않습니다.

URL로 반환된 provider 이미지 링크는 만료될 수 있습니다. 보관이 필요하면 직접 저장하거나 선택한 모델이 지원할 때 b64_json을 사용하세요.

이미지 편집#

POST/v1/images/edits

POST /v1/images/edits는 multipart로 원본 이미지를 편집합니다. OpenAI gpt-image-* 계열만 지원하며, SeedEdit URL i2i는 generations 경로를 사용하세요.

파라미터	타입	필수	설명
image	file	필수	편집할 원본 이미지 파일.
prompt	string	필수	편집 지시 텍스트.
mask	file	선택	선택. 편집할 영역을 표시하는 마스크.
model	string	선택	기본값 `gpt-image-2`.
n / size / response_format	optional	선택	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"

지원하지 않는 모델은 hold 전에 거절됩니다. 응답 형식은 generations와 동일합니다.