> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Muse Image Ext 이미지 생성 > 텍스트 또는 최대 9장의 참조 이미지로 요청당 WebP 이미지 1장을 생성합니다. > [!NOTE] > > 이 API는 비동기로 처리됩니다. 제출 후 작업 ID를 저장하고 `GET /v1/tasks/{task_id}`로 상태와 결과를 조회하세요. 기본 제출 응답의 ID 경로는 `data[0].task_id`입니다. ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Idempotency-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 }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.apimart.ai/v1/images/generations", headers={ "Authorization": "Bearer ", "Accept": "application/json", "Idempotency-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()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.apimart.ai/v1/images/generations", { method: "POST", headers: { Authorization: "Bearer ", "Content-Type": "application/json", Accept: "application/json", "Idempotency-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()); ``` ```json 200 theme={null} { "code": 200, "data": [ { "status": "submitted", "task_id": "task_01K..." } ] } ``` ## 요청 헤더 **Authorization** `string` *required* APIMart API Key를 `Bearer ` 형식으로 사용합니다. 제출과 조회 모두 동일한 사용자로 인증해야 합니다. **Idempotency-Key** `string` 사용을 강력히 권장합니다. 독립적인 생성마다 새 키를 사용하세요(표시 가능한 ASCII 문자 1–191자, UUID 권장). 예제의 ``를 실제 값으로 바꾸세요. 제출 시간 초과나 네트워크 오류로 재시도할 때는 엔드포인트, 본문, 응답 버전, 키를 동일하게 유지해야 합니다. 작업 ID를 받았다면 해당 작업만 조회하세요. ## 요청 매개변수 **model** `string` *required* 고정값: `muse-image-ext`. **prompt** `string` *required* 생성할 내용에 대한 설명입니다. 중국어와 영어를 지원하며, 앞뒤 공백을 제거한 후 비어 있으면 안 됩니다. 참조 이미지가 있어도 필수입니다. **image\_urls** `string[]` 비어 있지 않은 참조 이미지 입력을 최대 9개까지 받습니다. 공개 URL, Data URI(예: `data:image/png;base64,...`), 원시 base64를 지원합니다. 생략하거나 `[]`를 보내면 텍스트만으로 생성합니다. PNG, JPEG, WebP를 권장합니다. URL은 브라우저 로그인 쿠키 없이 서버에서 직접 접근할 수 있어야 합니다. 모든 참조 이미지의 원본 크기 합계는 **11 MiB(11,534,336바이트) 이하**여야 합니다. 이미지별 제한이 아닌 전체 제한입니다. base64 인코딩은 요청 본문 크기를 늘립니다. `blob:` URL, 로컬 파일 경로, `File` 객체를 보내지 마세요. **aspect\_ratio** `string` 아래 7가지 비율을 지원합니다. 생략하면 텍스트 기반 생성은 `1:1`, 참조 이미지 기반 생성은 참조 이미지의 구도를 따릅니다. 명시한 비율이 우선합니다. 자동 선택 시 이 필드를 생략하고 `"auto"`를 보내지 마세요. `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3` **size** `string` 호환 필드로 위 7가지 비율 또는 `auto`를 받으며, `1024x1024` 같은 픽셀 크기는 지원하지 않습니다. `size: "auto"`만 보내면 비율을 지정하지 않은 것과 같습니다. `aspect_ratio` 사용을 권장합니다. 두 필드가 유효하면 `aspect_ratio`가 우선하지만 각각 검증하므로 잘못된 `size`는 오류를 일으킵니다. **n** `integer` (default: 1) 요청당 결과는 1개입니다. 숫자 `1`만 허용합니다. `0`, 음수, `1`보다 큰 값을 명시하면 오류가 발생합니다. > [!NOTE] > > WebP URL을 반환합니다. 이미지 크기는 모델이 결정하며 픽셀 크기나 1K / 2K / 4K를 선택할 수 없습니다. 비어 있지 않은 `resolution`이나 시간 관련 필드를 보내지 마세요. ### 기타 선택 매개변수 **webhook** `string` 작업 알림을 수신하는 백엔드 기본 URL입니다. 끝의 슬래시를 제거한 뒤 `/callback`을 붙입니다. 예: `https://your-backend.example/muse` → `https://your-backend.example/muse/callback`. 조회만 사용한다면 생략할 수 있습니다. **language** `string` Webhook 오류 메시지의 언어이며 생성 내용에는 영향을 주지 않습니다. 지원 값: `zh`, `en`, `ja`, `ko`, `ru`, `fr`, `de`, `id`, `pt`, `es`. `zh-CN` 같은 지역 태그는 지원하지 않습니다. 조회 언어는 GET 쿼리 매개변수에 별도로 지정하세요. ## 참조 이미지를 사용하는 예제 ```json theme={null} { "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 } ``` 예제 URL을 접근 가능한 이미지 URL로 바꾸세요. 이 예제는 비율을 생략해 참조 이미지의 구도를 따릅니다. 고정하려면 `aspect_ratio`를 추가하세요. 여러 이미지는 `image_urls`에 추가하되 총 9장을 넘지 않아야 합니다. ## 제출 응답 기본 응답은 HTTP `200`이며 `data`는 배열입니다. `submitted`는 접수되었다는 의미이며 생성 완료를 뜻하지 않습니다. `data[0].task_id`를 저장한 후 작업을 조회하세요. > **선택적 응답 버전: 2026-07-27** > > `X-APIMart-Response-Version: 2026-07-27` 헤더를 보내면 HTTP `202`를 반환합니다. 작업 ID는 `data.id`, 조회 경로는 `data.poll_url`에서 읽습니다. > > ```json theme={null} > { > "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..." > } > } > ``` > > 이 버전은 GET 응답 구조를 바꾸지 않습니다. 이 헤더를 추가했다면 제출 응답을 `data[0].task_id`로 파싱하지 마세요. ## 작업 상태 및 결과 조회 제출 시 반환된 전체 작업 ID와 동일한 사용자 인증을 사용하세요. `language`는 오류 메시지 언어를 지정하는 선택 매개변수입니다. 전체 필드는 [작업 조회](https://docs.apimart.ai/ko/api-reference/tasks/status.md)를 참고하세요. ```bash theme={null} curl --request GET \ --url 'https://api.apimart.ai/v1/tasks/?language=ko' \ --header 'Authorization: Bearer ' ``` 5초 간격을 권장하며 같은 작업의 조회 요청이 겹치지 않도록 하세요. 클라이언트 시간 초과나 조회 중지는 서버 작업을 취소하지 않습니다. ID를 저장하고 나중에 GET 조회를 재개하세요. 새 생성을 자동으로 제출하지 마세요. | `data.status` | 처리 방법 | | - | - | | `pending` / `processing` | 대기 중 또는 처리 중입니다. 조회를 계속합니다. | | `completed` | 생성 성공. 조회를 중지하고 결과 URL을 읽습니다. | | `failed` | 생성 실패. 조회를 중지하고 `data.error.message`를 확인합니다. | | `unknown` / … | 상태가 불확실합니다. ID를 보관하고 제한된 횟수로 다시 조회하세요. 성공으로 처리하거나 자동으로 재생성하지 마세요. | 종료 여부는 `data.status`로 판단합니다. HTTP `200`이나 `progress: 100`만으로 생성 성공을 판단할 수 없습니다. 처리 중 `polling_error`도 최종 실패를 의미하지 않습니다. 완료된 작업의 조회 응답 예제(결과 URL은 예시 값): ```json theme={null} { "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`에 따라 대기한 후 재시도하세요. | 실패한 작업도 HTTP `200`을 반환할 수 있습니다. `data.status`와 `data.error.message`를 확인하세요. 제출 중 네트워크 오류나 `5xx`가 발생해도 이미 접수되었을 수 있으므로 즉시 새 키로 다시 제출하지 마세요. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.