이미지 모델
OneMux 이미지 모델 인터페이스를 통해 이미지를 생성하고 편집합니다.
인터페이스 안내
이미지 모델은 전용 Images 인터페이스를 사용합니다. 이미지 생성 요청을 /v1/chat/completions로 보내지 마세요.
- 이미지 생성:
POST https://api.onemux.net/v1/images/generations - 이미지 편집:
POST https://api.onemux.net/v1/images/edits - 인증:
Authorization: Bearer YOUR_API_KEY - 모델: 현재 모델 목록 인터페이스에서 반환된 실제 이미지 모델 ID를 사용합니다.
먼저 현재 사용 가능한 모델을 확인하세요.
curl https://api.onemux.net/v1/models \
-H "Authorization: Bearer $ONEMUX_API_KEY"
이미지 모델의 생성, 편집, 참조 이미지, 크기, 품질, 출력 형식 등의 매개변수 지원 여부는 모델 목록과 실제 업스트림 기능을 기준으로 합니다.
이미지 생성
/v1/images/generations을 사용해 텍스트로 이미지 생성 요청을 보냅니다.
curl https://api.onemux.net/v1/images/generations \
-H "Authorization: Bearer $ONEMUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_IMAGE_MODEL_ID",
"prompt": "一只坐在窗边的橘猫,午后自然光,写实摄影风格",
"size": "1024x1024",
"quality": "medium"
}'
주요 매개변수:
| 매개변수 | 필수 | 설명 |
|---|---|---|
model | 예 | 현재 사용 가능한 이미지 모델 ID |
prompt | 예 | 이미지 내용 설명 |
size | 아니요 | 이미지 크기. 지원 범위는 모델에 따라 다릅니다. |
quality | 아니요 | 이미지 품질. 지원 값은 모델에 따라 다릅니다. |
n | 아니요 | 생성 개수. 지원 범위는 모델에 따라 다릅니다. |
response_format | 아니요 | b64_json 또는 url. 지원하는 모델에서만 사용할 수 있습니다. |
background | 아니요 | 투명 또는 불투명 배경. 지원하는 모델에서만 사용할 수 있습니다. |
output_format | 아니요 | png, jpeg, webp. 지원하는 모델에서만 사용할 수 있습니다. |
특정 모델에서 지원되는 매개변수를 다른 이미지 모델에 그대로 사용하지 마세요. model_not_found, invalid_model 또는 매개변수 미지원 오류가 발생하면 먼저 모델 ID와 모델 기능을 확인하세요.
이미지 편집
/v1/images/edits을 사용해 기존 이미지를 편집합니다. 일반적인 OpenAI 호환 이미지 모델은 multipart/form-data을 사용해 이미지를 업로드합니다.
curl https://api.onemux.net/v1/images/edits \
-H "Authorization: Bearer $ONEMUX_API_KEY" \
-F "model=YOUR_IMAGE_MODEL_ID" \
-F "image[]=@input.png" \
-F "prompt=将背景改为浅蓝色,保持主体和文字不变" \
-F "size=1024x1024"
여러 참조 이미지는 image[]를 반복해 전달할 수 있습니다. 예를 들면 다음과 같습니다.
-F "image[]=@person.png" \
-F "image[]=@product.png"
이미지 개수, 이미지 형식, 마스크, 참조 이미지 URL 및 JSON 편집 형식은 모델과 업스트림 채널에 따라 다릅니다. 모델에서 명시적으로 지원하는 경우에만 이러한 매개변수를 사용하세요.
Python 호출
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["ONEMUX_API_KEY"],
base_url="https://api.onemux.net/v1",
)
result = client.images.generate(
model="YOUR_IMAGE_MODEL_ID",
prompt="一张简洁的蓝色科技风产品海报",
size="1024x1024",
)
print(result.data[0].b64_json or result.data[0].url)
이미지 편집은 일반적으로 multipart 파일을 직접 전송해야 합니다. 현재 Python SDK 버전에서 대상 모델의 편집 매개변수를 지원하지 않으면 위의 cURL 요청을 사용하세요.
반환 결과
성공 응답에는 일반적으로 data 배열이 포함됩니다.
{
"created": 1760000000,
"data": [
{
"b64_json": "iVBORw0KGgo..."
}
]
}
일부 모델은 response_format을 url로 요청하면 이미지 주소를 반환합니다.
{
"created": 1760000000,
"data": [
{
"url": "https://example.com/generated-image.png"
}
]
}
Base64가 반환되면 실제 이미지 형식에 맞춰 파일을 저장하세요. URL이 반환되면 임시 주소가 만료되기 전에 다운로드해 직접 저장하세요.
요금 안내
이미지 모델은 일괄적으로 Token 기준으로 요금이 청구되지 않습니다. OneMux는 모델에 현재 공지된 요금 규칙에 따라 정산하며, 다음과 같은 방식이 적용될 수 있습니다.
- 생성 이미지 수 기준 과금
- 이미지 해상도 또는 품질 등급 기준 과금
- 이미지 입력·출력 Token 또는 기타 업스트림 사용량 기준 과금
실제 가격, 과금 단위 및 지원 사양은 모델 카탈로그에서 해당 모델에 현재 안내된 내용을 따릅니다. 요청이 실패하면 일반적으로 성공 결과에 해당하는 이미지 요금은 발생하지 않지만, 구체적인 동작은 페이지에 표시된 내용과 서버 응답을 기준으로 합니다.
자주 묻는 질문
대화 인터페이스로 이미지를 생성할 수 없는 이유는 무엇인가요?
이미지 모델은 전용 Images 라우트를 사용합니다. /v1/chat/completions 또는 호환되지 않는 다른 인터페이스로 요청을 보내면 모델이 해당 엔드포인트를 지원하지 않는다는 오류나 매개변수 오류가 반환될 수 있습니다.
모델 이름을 조회할 수 있는데도 요청이 실패하는 이유는 무엇인가요?
모델이 이미지 생성 또는 이미지 편집을 지원하는지, 현재 API Key에 권한이 있는지, 요청 매개변수가 해당 모델의 지원 범위에 포함되는지, 해당 업스트림 채널을 사용할 수 있는지 확인하세요.
이미지 링크 대신 Base64가 반환되는 이유는 무엇인가요?
모델 또는 response_format 설정에 따라 반환 형식이 달라집니다. b64_json를 받으면 클라이언트에서 직접 디코딩해 저장해야 합니다. url을 받으면 반환된 주소에서 다운로드해야 합니다.
이미지 생성이 너무 느린 경우 어떻게 해야 하나요?
고해상도, 고품질 또는 복잡한 편집 요청은 처리 시간이 더 오래 걸릴 수 있습니다. 클라이언트에서 적절한 요청 타임아웃을 설정하고, 클라이언트 타임아웃만을 이유로 동일한 요청을 다시 제출하지 마세요. 중복 작업이나 요금이 발생할 수 있습니다.
GPT Image 2.6: SVG, GIF 및 복잡도
GPT Image 2.6 시리즈에는 SVG 출력, GIF 애니메이션 출력 및 complexity 매개변수가 추가되었습니다. 이러한 기능은 이를 지원하는 모델과 업스트림 채널에서만 사용할 수 있습니다.
SVG 출력
SVG는 이미지 생성에 사용하며 이미지 편집에는 사용하지 않습니다. 생성 인터페이스를 호출할 때 output_format를 svg로 설정하고 n을 1로 설정하세요. 응답의 이미지 데이터는 Base64입니다. 디코딩한 뒤 .svg 파일로 저장하세요.
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一个简洁的蓝色几何图形标志",
"output_format": "svg",
"n": 1
}
일부 업스트림 설정에서는 svg.model과 같은 추가 svg 객체가 필요할 수 있습니다. 모델 또는 채널 안내에 명시된 경우에만 추가하세요. 모든 이미지 모델과 채널이 SVG를 지원하는 것은 아닙니다.
GIF 애니메이션 출력
이 기능을 지원하는 GPT Image 2.6 모델은 이미지 생성 인터페이스에서 output_format을 gif로 설정할 수 있습니다. 모델이 지원하는 경우 frame_count과 frame_duration_ms를 사용해 애니메이션 프레임 수와 프레임당 재생 시간을 설정할 수 있습니다. GIF는 생성 기능이므로 이미지 편집 인터페이스에서도 GIF를 반환할 수 있다고 가정하지 마세요.
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一只蓝色小鸟循环拍打翅膀的动画",
"output_format": "gif",
"frame_count": 6,
"frame_duration_ms": 200
}
복잡도 매개변수
GPT Image 2.6 시리즈는 complexity를 지원하며 값은 low, medium, high입니다. 간단한 수정에는 낮은 복잡도를, 텍스트가 많거나 레이아웃이 복잡한 이미지에는 높은 복잡도를 사용해 볼 수 있습니다. 이 매개변수는 quality와 다르며, 복잡도가 높을수록 생성 시간이 더 길어질 수 있습니다.
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一张细节丰富的城市街景编辑插画",
"complexity": "high",
"quality": "high"
}
위 매개변수가 모든 모델에 공통으로 적용되는 것은 아닙니다. 인터페이스에서 매개변수 미지원 오류가 발생하면 선택적 매개변수를 제거하거나 선택한 모델과 채널의 기능을 확인하세요.