curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: <unique-operation-key>' \
--data '{
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Accept": "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
json={
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
body: JSON.stringify({
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
})
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
Muse Image Ext
Muse Image Ext 이미지 생성
텍스트 또는 최대 9장의 참조 이미지로 요청당 WebP 이미지 1장을 생성합니다.
POST
/
v1
/
images
/
generations
curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: <unique-operation-key>' \
--data '{
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Accept": "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
json={
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
body: JSON.stringify({
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
})
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
이 API는 비동기로 처리됩니다. 제출 후 작업 ID를 저장하고
GET /v1/tasks/{task_id}로 상태와 결과를 조회하세요. 기본 제출 응답의 ID 경로는 data[0].task_id입니다.curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: <unique-operation-key>' \
--data '{
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Accept": "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
json={
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
body: JSON.stringify({
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
})
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
요청 헤더
string
필수
APIMart API Key를
Bearer <token> 형식으로 사용합니다. 제출과 조회 모두 동일한 사용자로 인증해야 합니다.string
사용을 강력히 권장합니다. 독립적인 생성마다 새 키를 사용하세요(표시 가능한 ASCII 문자 1–191자, UUID 권장). 예제의
<unique-operation-key>를 실제 값으로 바꾸세요. 제출 시간 초과나 네트워크 오류로 재시도할 때는 엔드포인트, 본문, 응답 버전, 키를 동일하게 유지해야 합니다. 작업 ID를 받았다면 해당 작업만 조회하세요.요청 매개변수
string
필수
고정값:
muse-image-ext.string
필수
생성할 내용에 대한 설명입니다. 중국어와 영어를 지원하며, 앞뒤 공백을 제거한 후 비어 있으면 안 됩니다. 참조 이미지가 있어도 필수입니다.
string[]
비어 있지 않은 참조 이미지 입력을 최대 9개까지 받습니다. 공개 URL, Data URI(예:
data:image/png;base64,...), 원시 base64를 지원합니다. 생략하거나 []를 보내면 텍스트만으로 생성합니다. PNG, JPEG, WebP를 권장합니다. URL은 브라우저 로그인 쿠키 없이 서버에서 직접 접근할 수 있어야 합니다.모든 참조 이미지의 원본 크기 합계는 11 MiB(11,534,336바이트) 이하여야 합니다. 이미지별 제한이 아닌 전체 제한입니다. base64 인코딩은 요청 본문 크기를 늘립니다. blob: URL, 로컬 파일 경로, File 객체를 보내지 마세요.string
아래 7가지 비율을 지원합니다. 생략하면 텍스트 기반 생성은
1:1, 참조 이미지 기반 생성은 참조 이미지의 구도를 따릅니다. 명시한 비율이 우선합니다. 자동 선택 시 이 필드를 생략하고 "auto"를 보내지 마세요.1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3string
호환 필드로 위 7가지 비율 또는
auto를 받으며, 1024x1024 같은 픽셀 크기는 지원하지 않습니다. size: "auto"만 보내면 비율을 지정하지 않은 것과 같습니다. aspect_ratio 사용을 권장합니다. 두 필드가 유효하면 aspect_ratio가 우선하지만 각각 검증하므로 잘못된 size는 오류를 일으킵니다.integer
기본값:"1"
요청당 결과는 1개입니다. 숫자
1만 허용합니다. 0, 음수, 1보다 큰 값을 명시하면 오류가 발생합니다.WebP URL을 반환합니다. 이미지 크기는 모델이 결정하며 픽셀 크기나 1K / 2K / 4K를 선택할 수 없습니다. 비어 있지 않은
resolution이나 시간 관련 필드를 보내지 마세요.기타 선택 매개변수
string
작업 알림을 수신하는 백엔드 기본 URL입니다. 끝의 슬래시를 제거한 뒤
/callback을 붙입니다. 예: https://your-backend.example/muse → https://your-backend.example/muse/callback. 조회만 사용한다면 생략할 수 있습니다.string
Webhook 오류 메시지의 언어이며 생성 내용에는 영향을 주지 않습니다. 지원 값:
zh, en, ja, ko, ru, fr, de, id, pt, es. zh-CN 같은 지역 태그는 지원하지 않습니다. 조회 언어는 GET 쿼리 매개변수에 별도로 지정하세요.참조 이미지를 사용하는 예제
{
"model": "muse-image-ext",
"prompt": "Keep the cup from the reference image and place it on a wooden cafe table in warm natural light",
"image_urls": [
"https://your-cdn.example/cup.png"
],
"n": 1
}
aspect_ratio를 추가하세요. 여러 이미지는 image_urls에 추가하되 총 9장을 넘지 않아야 합니다.
제출 응답
기본 응답은 HTTP200이며 data는 배열입니다. submitted는 접수되었다는 의미이며 생성 완료를 뜻하지 않습니다. data[0].task_id를 저장한 후 작업을 조회하세요.
선택적 응답 버전: 2026-07-27
선택적 응답 버전: 2026-07-27
X-APIMart-Response-Version: 2026-07-27 헤더를 보내면 HTTP 202를 반환합니다. 작업 ID는 data.id, 조회 경로는 data.poll_url에서 읽습니다.{
"code": 202,
"request_id": "req_example",
"data": {
"id": "task_01K...",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01K..."
}
}
data[0].task_id로 파싱하지 마세요.작업 상태 및 결과 조회
제출 시 반환된 전체 작업 ID와 동일한 사용자 인증을 사용하세요.language는 오류 메시지 언어를 지정하는 선택 매개변수입니다. 전체 필드는 작업 조회를 참고하세요.
curl --request GET \
--url 'https://api.apimart.ai/v1/tasks/<task_id>?language=ko' \
--header 'Authorization: Bearer <token>'
data.status | 처리 방법 |
|---|---|
pending / processing | 대기 중 또는 처리 중입니다. 조회를 계속합니다. |
completed | 생성 성공. 조회를 중지하고 결과 URL을 읽습니다. |
failed | 생성 실패. 조회를 중지하고 data.error.message를 확인합니다. |
unknown / … | 상태가 불확실합니다. ID를 보관하고 제한된 횟수로 다시 조회하세요. 성공으로 처리하거나 자동으로 재생성하지 마세요. |
data.status로 판단합니다. HTTP 200이나 progress: 100만으로 생성 성공을 판단할 수 없습니다. 처리 중 polling_error도 최종 실패를 의미하지 않습니다.
완료된 작업의 조회 응답 예제(결과 URL은 예시 값):
{
"code": 200,
"data": {
"id": "task_01K...",
"status": "completed",
"progress": 100,
"result": {
"images": [
{
"url": [
"https://cdn.example/generated-image.webp"
]
}
]
}
}
}
data는 객체이며 url은 문자열 배열입니다. 첫 결과는 data.result.images[0].url[0]에 있습니다. expires_at이 있으면 Unix 초 단위 만료 시각이므로 필요한 파일을 만료 전에 저장하세요. actual_time은 작업 처리 시간이며 동영상 재생 시간이 아닙니다.
기능 제한 및 오류 처리
참조 동영상, 참조 오디오, 마스크, 시작/끝 프레임 제어, 연장, remix는 지원하지 않습니다.quality는 효과가 없습니다. seed, negative_prompt, width, height, response_format, output_format은 이 모델의 생성 매개변수가 아니므로 생략하세요. async: false로 동기 생성으로 전환할 수 없으며 stream은 SSE 생성 스트림을 제공하지 않습니다.
HTTP / error.code | 처리 방법 |
|---|---|
400 / invalid_request_error | 프롬프트, 참조 이미지 수, 비율, 출력 수, 고정 출력 사양을 확인하세요. |
409 / idempotency_in_progress | Retry-After에 따라 기다린 후 같은 멱등 키로 원래 요청을 재시도하세요. |
409 / idempotency_key_reused | 같은 키가 서로 다른 요청에 사용되었습니다. 키 사용을 수정하고 독립적인 생성마다 새 키를 사용하세요. |
409 / idempotency_result_indeterminate | 자동 재전송을 멈추고 확인을 위해 키와 작업 정보를 보관하세요. |
429 | Retry-After에 따라 대기한 후 재시도하세요. |
200을 반환할 수 있습니다. data.status와 data.error.message를 확인하세요. 제출 중 네트워크 오류나 5xx가 발생해도 이미 접수되었을 수 있으므로 즉시 새 키로 다시 제출하지 마세요.