POST /v1/images/

GPT Image 모델로 이미지를 생성하거나 참조 이미지 기반 편집하는 OpenAI Images 호환 API입니다. OpenAI SDK와 거의 동일하게 base_url을 4AICode로, api_key를 sk-4ai-... 토큰으로 바꾸면 됩니다.

이미지 생성은 지갑 잔액에서 요청당 과금됩니다. 콘솔 이미지 생성 페이지는 수동 사용에 적합하고, API는 자체 애플리케이션·워크플로·자동화 스크립트 연동용입니다.

신규 프로젝트는 GPT Image 2.5 권장: 고품질 생성·정밀 편집에는 gpt-image-2.5-sunburst, 일상 고품질 생성에는 가장 빠른 gpt-image-2.5-flare. 기존 연동은 gpt-image-2 계속 사용 가능.

엔드포인트

POST https://relay.4aicode.com/v1/images/generations
POST https://relay.4aicode.com/v1/images/edits

지원 모델

Model	용도	과금
`gpt-image-2.5-sunburst`	고품질 생성·정밀 편집용 최상급 GPT Image 2.5	지갑 잔액에서 요청당
`gpt-image-2.5-flare`	일상 고품질 생성용 빠른 GPT Image 2.5	지갑 잔액에서 요청당
`gpt-image-2`	텍스트→이미지 및 참조 기반 편집	지갑 잔액에서 요청당

각 모델은 관리자가 요청당 가격을 설정·활성화하고 업스트림 모델 목록에 선택한 뒤 사용 가능합니다. 비활성 시 API는 503 model_unavailable을 반환합니다.

텍스트→이미지 생성

curl

curl https://relay.4aicode.com/v1/images/generations \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "A clean product shot of a black mechanical keyboard on a white desk",
    "size": "1024x1024",
    "quality": "medium",
    "response_format": "b64_json"
  }'

Python

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://relay.4aicode.com/v1",
    api_key="sk-4ai-xxxxxxxxxxxxxxxx",
)

resp = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="A clean product shot of a black mechanical keyboard on a white desk",
    size="1024x1024",
    quality="medium",
    response_format="b64_json",
)

image_base64 = resp.data[0].b64_json
with open("keyboard.png", "wb") as f:
    f.write(base64.b64decode(image_base64))

TypeScript

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://relay.4aicode.com/v1",
  apiKey: process.env.OPENAI_API_KEY,
});

const resp = await client.images.generate({
  model: "gpt-image-2.5-sunburst",
  prompt: "A clean product shot of a black mechanical keyboard on a white desk",
  size: "1024x1024",
  quality: "medium",
  response_format: "b64_json",
});

const image = resp.data[0]?.b64_json;
if (!image) throw new Error("image generation failed");
fs.writeFileSync("keyboard.png", Buffer.from(image, "base64"));

참조 기반 이미지 편집

/v1/images/edits 입력 방식 두 가지:

multipart/form-data: image 또는 image[]로 파일 업로드. 파일당 최대 20 MB.
application/json: images[].image_url에 base64 data URL 또는 접근 가능한 이미지 URL.

multipart curl

curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -F model="gpt-image-2.5-sunburst" \
  -F prompt="Keep the product, replace the background with a bright studio setup" \
  -F size="1024x1024" \
  -F quality="medium" \
  -F response_format="b64_json" \
  -F image="@./product.png"

여러 참조 이미지:

curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -F model="gpt-image-2.5-sunburst" \
  -F prompt="Combine these references into one cohesive hero image" \
  -F image[]="@./subject.png" \
  -F image[]="@./style.png"

JSON Data URL

IMAGE_B64="$(base64 < product.png | tr -d '\n')"

curl https://relay.4aicode.com/v1/images/edits \
  -H "Authorization: Bearer sk-4ai-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"gpt-image-2.5-sunburst\",
    \"prompt\": \"Put this product in a premium ecommerce scene\",
    \"size\": \"1024x1024\",
    \"quality\": \"medium\",
    \"response_format\": \"b64_json\",
    \"images\": [
      { \"image_url\": \"data:image/png;base64,${IMAGE_B64}\" }
    ]
  }"

file_id는 현재 명시적 오류를 반환합니다. 마스크는 mask 파일 필드 또는 JSON의 mask.image_url로 제공하세요.

매개변수

매개변수	적용 엔드포인트	설명
`model`	전체	위 표에서 활성화된 모델 ID
`prompt`	전체	필수 생성/편집 지시
`size`	전체	`auto`, `1024x1024`, `1536x1024`, `1024x1536`
`quality`	전체	`auto`, `low`, `medium`, `high`; GPT Image 2.5는 `xhigh`, `max`도 지원
`response_format`	전체	`b64_json` 또는 `url`; `url`은 data URL 반환
`output_format`	전체	`png`, `jpeg`, `webp`
`background`	전체	업스트림 이미지 도구로 전달
`output_compression`	전체	압축 지원 형식의 출력 압축률
`stream`	전체	`true`면 SSE 반환
`partial_images`	전체	스트리밍에서 partial-image 이벤트 요청
`image` / `image[]`	edits	multipart 참조 이미지
`images[].image_url`	edits	JSON 참조 URL 또는 data URL
`mask` / `mask.image_url`	edits	선택 마스크
`input_fidelity`	edits	참조 이미지 충실도, 업스트림으로 전달

응답

비스트리밍은 OpenAI Images 스타일:

{
  "created": 1770000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...",
      "revised_prompt": "..."
    }
  ],
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "usage": {
    "images": 1
  }
}

response_format=url이면 data[].url에 data:image/png;base64,... 형태로 이미지가 응답에 포함됩니다.

스트리밍 응답

"stream": true로 SSE.

텍스트→이미지 이벤트:

event: image_generation.partial_image
data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"..."}

event: image_generation.completed
data: {"type":"image_generation.completed","b64_json":"...","usage":{"images":1}}

참조 편집은 image_edit 접두사:

event: image_edit.completed
data: {"type":"image_edit.completed","b64_json":"...","usage":{"images":1}}

과금 및 기록

성공한 생성마다 선택 모델의 현재 요청당 가격으로 청구됩니다. 사용량 페이지, 지갑 거래 내역, 백엔드 사용 로그에 모델, 요청 수, 비용, 상태, trace ID가 기록됩니다. 기본적으로 프롬프트·이미지 내용은 저장하지 않습니다.

자주 발생하는 오류

HTTP	code	해결
400	`invalid_request_error`	`prompt`, `model`, 이미지 필드, multipart 형식 확인
401	`unauthorized`	`Authorization: Bearer sk-4ai-...` 확인
429	`insufficient_quota` / `rate_limit`	지갑 충전 또는 동시성 감소
503	`model_unavailable`	관리자에게 선택 이미지 모델 요청당 가격 활성화 요청
502	`upstream_error`	나중에 재시도; 지속 시 trace ID와 함께 지원 문의