> ## 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. # Seedream 5.5 이미지 생성 > 텍스트 또는 최대 10장의 참조 이미지로 이미지를 생성합니다. 투명 배경, 레이어 수 조절, 텍스트 OCR을 지원하는 비동기 API입니다. ```bash cURL theme={null} curl --request POST \ --url https://api.apimart.ai/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "seedream-5-5", "prompt": "An orange cat sticker with clean edges", "size": "2K", "background": "transparent", "output_format": "png" }' ``` ```python Python theme={null} import requests payload = { "model": "seedream-5-5", "prompt": "An orange cat sticker with clean edges", "size": "2K", "background": "transparent", "output_format": "png" } response = requests.post( "https://api.apimart.ai/v1/images/generations", headers={"Authorization": "Bearer "}, json=payload, timeout=60, ) response.raise_for_status() print(response.json()) ``` ```javascript JavaScript theme={null} const payload = { "model": "seedream-5-5", "prompt": "An orange cat sticker with clean edges", "size": "2K", "background": "transparent", "output_format": "png" }; const response = await fetch("https://api.apimart.ai/v1/images/generations", { method: "POST", headers: { "Authorization": "Bearer ", "Content-Type": "application/json" }, body: JSON.stringify(payload) }); 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_example_seedream55" } ] } ``` `POST /v1/images/generations`로 요청한 후 `data[0].task_id`를 저장하고 `GET /v1/tasks/{task_id}`로 결과를 조회합니다. ## 모드 | 모드 | 설정 | 입력 이미지 | 프롬프트 | | - | - | - | - | | 이미지 생성 | 기본값 | 0\~10장 | 필수 | | 레이어 분해 | `layer_decomposition: true` | 정확히 1장 | 선택 | ## 인증 **Authorization** `string` *required* `Authorization: Bearer `을 사용합니다. ``은 APIMart API Key입니다. ## 요청 매개변수 **model** `string` *required* `seedream-5-5`를 지정합니다. **prompt** `string` 텍스트 및 이미지 기반 생성에서는 필수입니다. 레이어 분해에서는 생략하면 피사체, 텍스트, 배경을 자동 식별합니다. 분리할 요소를 프롬프트로 지정할 수도 있습니다. **image\_urls** `string[]` 일반 생성은 참조 이미지 최대 10장, 분해는 정확히 1장입니다. 공개 이미지 URL 또는 이미지 Base64 Data URI를 지원합니다. 로컬 파일은 [이미지 업로드 API](https://docs.apimart.ai/ko/api-reference/uploads/images.md)로 업로드한 뒤 반환된 `url`을 전달합니다. 참조 이미지는 공개 접근 가능한 `http(s)` URL 또는 `data:image/;base64,…`를 사용하세요. Data URI의 형식 이름은 소문자로 지정합니다. * JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF를 지원하며 AVIF와 JP2는 지원하지 않습니다. * 이미지당 **30 MiB(31,457,280바이트) 이하**, **총 3600만 픽셀 이하**입니다. 너비 × 높이로 계산하며 각 변의 상한이 6000픽셀이라는 뜻은 아닙니다. * 크기나 총 픽셀 초과는 동기 HTTP 400을 반환합니다. AVIF와 JP2는 작업 생성 후 상위 서비스에서 거부될 수 있으며 실패 시 환불됩니다. 제출 전에 형식을 변환하세요. 이미지 업로드 API에는 별도의 형식 제한이 있습니다. 모델은 지원하지만 업로드 API가 지원하지 않는 형식은 공개 URL 또는 Data URI로 전달하세요. **size** `string` 일반 생성 기본값은 `2K`이며 해상도 등급, 종횡비, 정확한 픽셀 크기를 지원합니다. 레이어 분해 기본값은 `auto`이며 `1K` / `1.5K` / `2K` / `auto`만 지원합니다. 이미지 생성에서 `size: "auto"`는 `2K`와 같습니다. 비율 형식에서 `resolution`을 생략해도 `2K`를 사용합니다. 정확한 픽셀 지정 시 `resolution`을 보내지 말고 너비와 높이를 양의 정수로 지정하세요. **resolution** `string` 일반 생성은 종횡비 형식의 `size`와 함께 `1K` / `1.5K` / `2K`를 사용합니다. 분해에서는 플랫폼이 제공하는 `size`의 별칭입니다. `size`가 우선하며 생략한 경우에만 `resolution`을 사용하고, 둘 다 없으면 `auto`입니다. 분해는 `1K` / `1.5K` / `2K` / `auto`만 허용하며 비율이나 픽셀 표기는 동기 HTTP 400을 반환합니다. `3K` / `4K`는 지원하지 않습니다. **background** `string` 일반 생성은 `auto`(기본값), `transparent`, `opaque`를 지원합니다. 텍스트 및 이미지 기반 생성 모두 투명 배경을 지원합니다. 투명 배경은 PNG만 가능하며 `output_format: "jpeg"`와 함께 사용할 수 없습니다. 분해에서는 `auto`를 포함해 이 필드를 생략해야 합니다. **output\_format** `string` (default: png) `png`(기본값) 또는 `jpeg`. 분해에서는 기본 이미지에만 적용되며 분리된 레이어는 항상 투명 PNG입니다. **n** `integer` `1`만 허용합니다. 일반 생성은 요청당 1장을 출력하며, 분해 개수는 `layer_decomposition_options.max_images`로 조절합니다. **watermark** `boolean` (default: false) 워터마크 추가 여부를 정하는 선택 항목입니다. **optimize\_prompt\_options** `object` `{"mode":"standard"}`만 지원합니다. 생략해도 업스트림 기본값인 `standard`가 활성화되며 Seedream 5.5에서는 최적화를 끌 수 없습니다. `disabled` / `none` / `off`는 업스트림에서 HTTP 400 및 `must be one of: standard`로 거부합니다. `fast`는 플랫폼 접수 단계에서 즉시 HTTP 400을 반환합니다. **layer\_decomposition** `boolean` `true`이면 기본 이미지와 투명 레이어로 분해합니다. 입력은 정확히 1장이어야 하며 `background`를 전달할 수 없습니다. `output_format`은 기본 이미지에만 적용됩니다. **layer\_decomposition\_options** `object` `layer_decomposition: true`에서만 허용합니다. 그 외에는 HTTP 400을 반환합니다. **요청 매개변수** **max\_images** `integer` (default: 30) `2`\~`100`의 정수이며 기본값은 `30`입니다. 기본 이미지를 포함한 총 출력 상한으로, 지정한 수만큼 생성을 보장하지는 않습니다. **text\_recognition** `boolean` (default: false) 선택적 불리언 값입니다. `true`로 설정하면 텍스트 레이어의 서식 있는 OCR을 요청합니다. 식별 가능한 일반 텍스트에서만 `text_recognition`이 반환될 수 있습니다. OCR을 켠 상태에서 `prompt`를 보내면 텍스트 인식 결과가 반환되지 않을 수 있습니다. OCR이 우선이라면 분해 프롬프트를 생략해 보세요. 반환이 보장되지는 않으므로 선택 필드로 처리해야 합니다. ## 크기 지정 | 형식 | 예시 | 규칙 | | - | - | - | | 해상도 등급 | `"size": "2K"` | `1K` / `1.5K` / `2K`. 일반 생성 기본값은 `2K`이며 비율은 프롬프트에 따라 결정됩니다. | | 종횡비 + 등급 | `"size": "16:9", "resolution": "1.5K"` | 일반 생성 전용. 아래 비율과 `16x9` 표기도 지원합니다. | | 정확한 픽셀 | `"size": "2048x1152"` | 일반 생성 전용. 총 픽셀 921,600~~4,624,220, 너비/높이 1/16~~16. | 지원 비율: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `21:9`, `2:1`, `1:2`. 픽셀 제한은 너비와 높이의 곱 및 비율에 적용됩니다. 분해는 등급 또는 `auto`만 허용하며 종횡비나 픽셀 크기는 사용할 수 없습니다. ### 레이어 분해 출력 크기 * 우선순위는 `size` → `resolution` → `auto`입니다. `resolution`은 플랫폼 별칭이며 업스트림에는 `size`만 전달됩니다. `size: "1K"`와 `resolution: "2K"`를 함께 보내면 `1K`, `resolution: "1.5K"`만 보내면 `1.5K`를 사용합니다. * `1K` / `1.5K` / `2K`를 지정하면 기본 이미지와 각 레이어가 자체 비율을 유지하면서 선택한 등급으로 출력됩니다. 실측 `1K` 예시의 기본 이미지는 `840×1248`이었고 각 레이어도 약 105만 픽셀이었습니다. 고정 너비와 높이는 아닙니다. * `auto`는 입력 원본 크기를 사용하되 `1K` 미만은 `1K`로 확대하고 `2K` 초과는 `2K`로 축소합니다. ## 요청 예시 ### 이미지 편집 및 참조 융합 ```bash theme={null} curl --request POST \ --url https://api.apimart.ai/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "seedream-5-5", "prompt": "Combine the product in the first image with the setting in the second image", "image_urls": ["https://example.com/product.png", "https://example.com/setting.jpg"], "size": "16:9", "resolution": "1.5K", "output_format": "png" }' ``` ### 레이어 분해 및 텍스트 OCR 기본 이미지를 포함하여 최대 10장을 요청합니다. `prompt`는 생략할 수 있으며 `background`는 전달하지 않습니다. 이미지 URL을 접근 가능한 주소로 바꾸세요. ```bash theme={null} curl --request POST \ --url https://api.apimart.ai/v1/images/generations \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "model": "seedream-5-5", "image_urls": ["https://example.com/poster.png"], "layer_decomposition": true, "layer_decomposition_options": { "max_images": 10, "text_recognition": true }, "size": "1K" }' ``` ## 작업 조회 [작업 조회 API](https://docs.apimart.ai/ko/api-reference/tasks/status.md)를 사용합니다. 처음 30초는 3초 간격, 이후에는 5\~10초 간격으로 조회하세요. 분해는 수분이 걸릴 수 있으며 서버 대기 상한은 13분입니다. `task_id`를 저장하고 종료 상태까지 조회하며 생성 요청을 중복 제출하지 마세요. ```bash theme={null} curl --request GET \ --url 'https://api.apimart.ai/v1/tasks/task_example_seedream55' \ --header 'Authorization: Bearer ' ``` `data.status`에서 `pending` / `processing`은 처리 중, `completed`는 성공입니다. `failed`이면 `data.error.message`를 확인하세요. 실패 비용은 자동 환불됩니다. 성공 이미지 URL은 `data.result.images[].url[]`에 있습니다. > [!WARNING] > > 결과 이미지는 **3일** 동안 보관되므로 빠르게 다운로드하세요. 작업 기록도 3일만 보관되며 이후에는 `task_id`로 조회할 수 없습니다. > > `data.result.images[].expires_at`은 현재 작업 완료 시각 + 24시간을 Unix 초 단위로 반환합니다. 실제 삭제보다 이른 보수적 표시이므로 실제 보관 기간이나 삭제 카운트다운 계산에 사용하지 마세요. ## 레이어 결과 및 OCR 아래는 구조를 설명하는 예시이며 실제 실행 기록이 아닙니다. 크기, 좌표, 텍스트는 예시 값입니다. 메타데이터는 없을 수 있으므로 선택 항목으로 처리하세요. ```json theme={null} { "code": 200, "data": { "id": "task_example_seedream55", "status": "completed", "progress": 100, "completed": 1794302642, "result": { "images": [ { "url": ["https://example.com/base.png", "https://example.com/title.png"], "sizes": ["840x1248", "1512x702"], "output_formats": ["png", "png"], "backgrounds": ["opaque", "transparent"], "expires_at": 1794389042, "layer_decomposition": true, "layers": [ { "z_index": 0, "size": "840x1248", "output_format": "png", "background": "opaque" }, { "z_index": 1, "size": "1512x702", "output_format": "png", "background": "transparent", "name": "Sale title", "description": "Printed sale title", "bounding_box": { "absolute": [84, 156, 756, 468], "normalized": [100, 125, 900, 375] }, "text_recognition": { "text": "SUMMER SALE", "lines": [ { "bounding_box": { "absolute": [126, 156, 714, 468], "normalized": [150, 125, 850, 375] }, "runs": [ { "text": "SUMMER SALE", "style": { "similar_font_family": "Arial", "foreground_color": "#222222", "bold": true, "italic": false, "underline": false, "strikethrough": false, "shadow": false, "translucent": false } } ] } ] } } ] } ] } } } ``` 각 `data.result.images[]`의 `url`, `sizes`, `output_formats`, `backgrounds`, `layers`는 같은 인덱스로 대응합니다. 메타데이터 배열 길이가 `url`과 다르면 해당 필드가 생략될 수 있습니다. | 필드 | 설명 | | - | - | | `url[]` | 이미지 URL. 분해에서는 0번이 기본 이미지이며 나머지는 레이어입니다. 파일은 다운로드하여 보관하세요. | | `sizes[]` / `output_formats[]` | 각 이미지의 실제 크기와 형식. | | `backgrounds[]` | 실제 배경은 `opaque` / `transparent`입니다. `background: "auto"`이면 반환값을 확인하세요. | | `expires_at` | 현재 작업 완료 시각 + 24시간(86400초)의 Unix 타임스탬프입니다. 보수적 표시이며 실제 이미지 삭제 시각이 아니므로 삭제 카운트다운에 사용하지 마세요. | | `layer_decomposition` | 레이어 분해 결과 여부. | | `layers[i].z_index` | 쌓는 순서. 기본 이미지는 0이며 오름차순으로 합성합니다. | | `layers[i].background` | 기본 이미지는 `opaque`, 분리 레이어는 `transparent`입니다. | | `layers[i].name` / `description` | 선택적 레이어 이름과 설명. | | `layers[i].bounding_box` | `absolute`는 기본 이미지 픽셀 좌표 `[left, top, right, bottom]`, `normalized`는 같은 상자의 0\~1000 정규화 좌표입니다. 기본 이미지에는 없습니다. | | `layers[i].text_recognition` | OCR을 켜고 일반 텍스트를 인식한 경우에만 있을 수 있습니다. 장식 글자, 손글씨, 비텍스트 레이어에는 없습니다. | 절대 좌표는 `x=left`, `y=top`, `w=right-left`, `h=bottom-top`입니다. `W × H` 캔버스에는 정규화 좌표를 다음과 같이 변환합니다. ```text theme={null} x = left / 1000 * W y = top / 1000 * H w = (right - left) / 1000 * W h = (bottom - top) / 1000 * H ``` 각 레이어는 선택한 등급으로 개별 출력되므로 파일 크기와 `bounding_box` 크기가 다를 수 있습니다. 합성할 때 레이어를 상자의 `w × h`로 조절한 뒤 `(x, y)`에 배치하세요. 레이어 파일 픽셀을 기본 이미지 좌표로 바로 사용하지 마세요. ### 텍스트 인식 필드 `text_recognition`은 상위 모델의 OCR 구조를 따릅니다. 플랫폼은 `text`, `lines`, `runs`, `style` 등의 필드를 그대로 전달합니다. | 필드 | 설명 | | - | - | | `text` | 레이어 전체 텍스트이며 줄바꿈은 `\n`입니다. | | `lines[].bounding_box` | 기본 이미지 좌표계의 행 경계 상자. | | `lines[].runs[]` | 같은 행에서 스타일이 다른 텍스트 조각으로, `text`와 `style`을 포함합니다. | | `runs[].style.similar_font_family` | 가장 가까운 글꼴 이름. 알 수 없으면 `unknown`. | | `runs[].style.foreground_color` | `#RRGGBB` 형식의 글자 색. | | `runs[].style.bold` / `italic` / `underline` / `strikethrough` / `shadow` / `translucent` | 모델이 추정한 불리언 스타일 정보이며 오차가 있을 수 있습니다. | OCR과 글꼴 정보는 표시, 복사, 편집을 돕지만 원본과 완전히 일치하지 않을 수 있습니다. OCR이 없어도 레이어 이미지는 사용할 수 있습니다. ## 과금 출력 이미지와 입력 참조 이미지는 별도 과금됩니다. **첫 번째를 포함한 모든 참조 이미지에 과금**하며 레이어 분해에 쓰는 입력 1장도 포함됩니다. * 각 출력의 실제 총 픽셀이 **2,610,000 이하**이면 낮은 요금 구간, 초과하면 높은 구간입니다. `1K` / `1.5K`는 낮은 구간, `2K`는 높은 구간에 해당하며 정확한 크기는 너비 × 높이로 계산합니다. * 이미지 생성은 선택한 출력 구간 요금과 참조 이미지 수 × 입력 단가를 선차감합니다. `size` 생략 또는 `auto`는 `2K`로 선차감합니다. * 레이어 분해는 `max_images` × 출력 선차감 구간 단가에 **입력 이미지 1장 요금**을 더합니다. 기본 `max_images`는 바탕 이미지를 포함한 30장이며 실제 출력은 더 적을 수 있습니다. * 분해는 적용되는 `size`(생략 시 `resolution`)에 따라 `1K` / `1.5K`는 낮은 구간, `2K` / `auto`는 높은 구간으로 선차감합니다. 둘 다 생략하면 높은 구간의 `auto`입니다. * 완료 시 실제 출력 수, 각 출력의 실제 픽셀 구간, 입력 수로 정산하고 차액을 환불하거나 추가 청구합니다. 바탕 이미지와 각 레이어를 1장씩 계산하며 요청 구간을 모든 출력에 일괄 적용하지 않습니다. 실패 시 전액 환불합니다. 단가는 [모델 요금](https://apimart.ai/pricing)을 확인하세요. ## 자주 발생하는 매개변수 오류 플랫폼 및 업스트림 검증 오류를 포함합니다. 제출 실패는 `error.message`, 비동기 작업 실패는 `data.error.message`를 확인하세요. | 오류 내용 | 해결 방법 | | - | - | | `does not support optimize_prompt_options.mode=fast` | 플랫폼 접수 단계에서 동기 HTTP 400을 반환합니다. `standard`만 가능하며 생략해도 최적화가 켜집니다. | | `must be one of: standard` | 업스트림 HTTP 400: `disabled` / `none` / `off`는 지원하지 않으며 최적화를 끌 수 없습니다. | | `only supports background auto, transparent or opaque` | `auto`, `transparent`, `opaque`를 사용하세요. | | `cannot combine background=transparent with output_format=jpeg` | 투명 배경은 `output_format: "png"`를 사용하세요. | | `does not accept background when layer_decomposition=true` | 분해 요청에서 `auto`를 포함해 `background`를 삭제하세요. | | `layer_decomposition_options requires layer_decomposition=true` | 분해 모드에서만 전달하세요. | | `layer_decomposition_options.max_images must be within [2, 100]` | `max_images`는 기본 이미지를 포함한 2\~100의 정수입니다. | | `invalid layer_decomposition_options` | `max_images`는 문자열이나 소수가 아닌 정수, `text_recognition`은 불리언이어야 합니다. | | `with layer_decomposition=true requires exactly 1 input image` | 분해 입력은 정확히 1장이어야 합니다. | | `only supports size 1K, 1.5K, 2K or auto` | 분해는 `size`를 우선하고 없으면 `resolution`을 사용합니다. `1K` / `1.5K` / `2K` / `auto`만 허용하며 비율이나 픽셀 표기는 동기 HTTP 400입니다. | | `` `n` must be 1 `` | `n`은 `1`이어야 하며 묶음 생성은 지원하지 않습니다. | | `does not support stream` / `does not support tools` | `sequential_image_generation`, `stream`, `tools`를 삭제하세요. | | `supports up to 10 reference images` | 참조 이미지는 최대 10장입니다. | | `reference image too large for seedream-5-5` | 참조 이미지당 30 MiB 및 총 3600만 픽셀을 넘을 수 없습니다. 압축하거나 크기를 줄이세요. | | `does not support size` / `requires total pixels` / `requires aspect ratio` | 총 픽셀, 비율, 크기 표기를 확인하세요. 3K / 4K는 지원하지 않습니다. | | `` `prompt` parameter is required `` | 이미지 생성에는 프롬프트가 필수입니다. 레이어 분해에서만 생략할 수 있습니다. | ## 작업 실패 원인 `data.status`가 `failed`이면 `data.error.message`와 `data.error.reason`을 확인하세요. 실패 요금은 자동 환불됩니다. `reason`이 없거나 알 수 없는 값이면 `message`를 표시하세요. | `data.error.reason` | 처리 방법 | | - | - | | `content_policy_violation` | 입력 또는 출력이 콘텐츠 검토를 통과하지 못했습니다. 프롬프트나 이미지를 수정하세요. | | `invalid_parameter` / `unsupported_option` | 지원하지 않는 매개변수 또는 조합입니다. 요청을 수정하세요. | | `invalid_media` | 입력 이미지가 손상되었거나 형식이 지원되지 않습니다. 확인 후 변환하세요. | | `media_unreachable` | 이미지 URL에 접근할 수 없습니다. 공개 접근 권한을 확인하거나 다시 업로드하세요. | | `generation_timeout` | 생성 시간이 초과되었습니다. 나중에 재시도하세요. | | `service_unavailable` | 서비스가 일시적으로 혼잡합니다. 나중에 재시도하세요. | | `delivery_failed` / `internal_error` / `unknown_error` | 전달 또는 플랫폼 내부 오류입니다. 반환된 설명에 따라 나중에 재시도하세요. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.