이미지 생성 API 문서

KozeAI는 OpenAI 스타일의 이미지 생성 및 편집 인터페이스를 제공합니다. 이미지 인터페이스는 균일한 이미지 응답 형식을 반환하지만, 특정 모델에서 지원하는 크기, 품질, 참조 이미지 및 출력 형식은 채널 어댑터에 따라 결정됩니다.

인증

모든 요청은 Authorization: Bearer 을 통해 인증됩니다. 콘솔에서 API 토큰을 생성한 후 사용합니다.

export KOZEAI_API_KEY='sk-your-token'

export KOZEAI_BASE_URL='https://your-kozeai-domain'

API 개요

<표> <머리글> 메서드 경로 콘텐츠 유형 목적 POST /v1/images/generations application/json 텍스트로 생성된 이미지 이미지 모델은

/v1/chat/completions

를 통해서도 호출할 수 있습니다. 채팅 인터페이스는 텍스트와 메시지에서 이미지를 추출한 다음 이미지 인터페이스 형식으로 변환합니다.

직접 연결할 때는 위의 전용 이미지 인터페이스를 사용하는 것이 좋습니다.

1. 文生图

curl '$KOZEAI_BASE_URL/v1/images/generations' \

-H 'Authorization: Bearer $KOZEAI_API_KEY' \

-H 'Content-Type: application/json' \

-d '{

'model': 'gpt-image-1',

'prompt': '창가에 앉아 있는 주황색 고양이, 영화 같은 빛과 그림자',

'n': 1,

'size': '1024x1024',

'quality': 'auto',

'response_format': 'url'

}

요청 매개변수

매개변수 <테이블> <헤드> 매개변수 유형 필수 설명 모델 문자열 예 이미지 모델 이름입니다. 실제로 사용 가능한 모델은 /v1/models에서 반환되는 값을 기반으로 합니다. 프롬프트 문자열 예 이미지 콘텐츠 설명입니다. 비어 있지 않은 문자열을 사용하는 것이 좋습니다. n 정수 아니요 생성되는 요소 개수, 기본값 1, 일반적인 유효성 검사 범위는 1-10입니다. 크기 문자열 아니요 이미지 크기 또는 종횡비, 특정 값은 모델에 의해 결정됩니다. 품질 문자열 아니요 품질 수준, 일반적 값은 standard, hd, auto, 2k, 4k입니다. response_format string 아니요 일반적인 값은 url 또는 b64_json입니다. 스타일 모든 아니요 OpenAI 호환 스타일 매개변수입니다. 사용자 / 사용자 ID 모든 아니요 호출자 사용자 식별자입니다. 추가 필드 객체 아니요 추가 구조화된 매개변수; 효과는 채널 어댑터에 따라 달라집니다. 배경 없음 아니요 배경 설정. 검열 없음 아니요 콘텐츠 검열 설정. 출력 형식 없음 아니요 출력 이미지 형식. output_compression 정수 아니요 일부 코덱스 이미지 모델에서 지원하는 출력 압축 매개변수입니다. partial_images 정수 아니요 일부 코덱스 이미지 모델에서 지원하는 이미지/스트리밍 관련 매개변수입니다. watermark boolean 아니요 워터마크 활성화/비활성화 여부. 채널에 따라 효과가 달라집니다. watermark_enabled any No 일부 상위 워터마크 매개변수와 호환됩니다. image string/object/array No 이미지 URL, 데이터 URL 또는 이미지 객체를 참조하세요. 일부 채널은 자동으로 편집 프로세스에 들어갑니다.

DALL·E 크기 및 기본값

dall-e-3

모델	크기 허용 값	기본값
dall-e-2 / dall-e	256x256、512x512、1024x1024	1024x1024
1024x1024、1024x1792、1792x1024	1024x1024
gpt-image-1 / gpt-image-2	상위 모델에 의해 결정됨	quality=auto

크기 반각 문자 x를 사용해야 하며, 곱셈 기호 ×는 사용할 수 없습니다.

2. 이미지 편집

표준 편집 요청은 image라는 이름의 이미지 필드를 사용하는 멀티파트 폼을 사용합니다. image 또는 image[]를 사용하여 여러 입력 이미지를 재사용할 수 있습니다.

curl '$KOZEAI_BASE_URL/v1/images/edits' \
-H 'Authorization: Bearer $KOZEAI_API_KEY' \
-F 'model=gpt-image-1' \
-F 'prompt=배경을 야경으로 변경하고 피사체 세부 정보는 유지합니다.' \
-F 'image=@./input.png' \
-F 'n=1' \
-F 'quality=standard'

일반 양식 필드:

필드	유형	설명
모델	문자열	이미지 편집 모델.
프롬프트	문자열	편집 요구 사항.
이미지 / image[]	파일	이미지를 하나 이상 입력하세요.
마스크	파일	이미지를 마스크합니다; 주로 OpenAI/Codex 호환 편집 워크플로에 사용됩니다.
n	정수	생성되는 요소 개수, 기본값 1, 범위 1-10.
size	string	출력 크기 또는 비율.
quality	string	출력 품질.
응답 형식	문자열	url 또는 b64_json (채널에 따라 다름)
워터마크	부울	워터마크 표시 여부 (채널에 따라 다름)

일부 채널은 image를 데이터 URL 또는 이미지 URL로 설정하는 것과 같은 JSON 편집 요청도 지원합니다. 하지만 OpenAI, Codex, ChatGPT OAuth 편집 경로는 멀티파트 형식을 우선적으로 사용합니다.

3. 채널 차이점

채널	추가 동작
OpenAI / DALL·E	OpenAI 이미지 필드에서 전달됩니다. DALL·E는 크기에 대한 엄격한 유효성 검사를 수행합니다.
xAI	크기는 종횡비 및 해상도로 변환됩니다. 응답 형식은 기본적으로 b64_json입니다. 종횡비 및 해상도와 같은 추가 JSON 매개변수가 지원됩니다.
흐름	크기 1:1, 16:9, 9:16, 4:3, 3:4의 화면비를 지원합니다. quality=2k/4k를 입력하면 크기 조정이 시작됩니다. 참조 이미지는 image를 통해 업로드됩니다.
지멍 / 드림이나	크기는 화면비 매핑에 사용됩니다. quality=hd를 입력하면 더 높은 해상도가 선택되고, 참조 이미지가 블렌딩 프로세스에 들어갑니다.
Codex	추가적으로 input_fidelity, mask, stream, output_format, output_compression, partial_images를 지원합니다.
ChatGPT OAuth	실제로는 model, prompt, n을 사용하고 이미지를 편집합니다. 다른 이미지 매개변수는 무시될 수 있습니다.
Grok	response_format url 또는 b64_json만 지원하며 기본값은 url입니다. 편집 요청에는 최소 하나 이상의 이미지가 필요합니다.

공개 필드에 정의되지 않은 매개변수는 자동으로 전달되지 않습니다. 해당 채널 어댑터에서 명시적으로 읽은 추가 매개변수만 적용됩니다.

4. 응답 형식

{

"created": 1751000000,

"data": [
{
"url": "https://example.com/generated.png",

"b64_json": "",

"revised_prompt": "창가에 앉아 있는 주황색 고양이, 영화 같은 빛과 그림자"

}
]

}

`response_format=b64_json`인 경우 이미지 콘텐츠는 `data[].b64_json`에 있습니다. URL 형식을 사용하는 경우 이미지 주소는 `data[].url`에 있습니다. 채널에 따라 사용되지 않는 필드에 빈 문자열이 반환될 수 있습니다.

5. JavaScript 호출 예시

const baseURL = process.env.KOZEAI_BASE_URL;

const apiKey = process.env.KOZEAI_API_KEY;

const response = await fetch(`${baseURL}/v1/images/generations`, {

method: 'POST',

headers: {
Authorization: `Bearer ${apiKey}`,

'Content-Type': 'application/json',

},

body: JSON.stringify({
model: 'gpt-image-1',

prompt: '흰색 배경의 미니멀한 제품 일러스트',

n: 1, size: 1024x1024,

response_format: url,

}),

});

if (!response.ok) {

throw new Error(await response.text());

}
const result = await response.json();

console.log(result.data[0].url || result.data[0].b64_json);

6. 일반적인 오류

• model이 필수입니다: 모델 이름이 전달되지 않았습니다.
• prompt가 필수입니다: 프롬프트 단어가 비어 있습니다.
• n은 1에서 10 사이여야 합니다: 생성 수량이 공용 제한을 초과했습니다.
• size는 다음 중 하나여야 합니다...: DALL·E에서 지원되지 않는 크기를 사용하고 있습니다.
• image가 필수입니다: 편집 인터페이스에서 이미지를 업로드하지 않았거나 인식 가능한 이미지 참조를 제공하지 않았습니다.
• 지원되지 않는 ... response_format: 대상 채널에서 요청된 출력 형식을 지원하지 않습니다.