Seedream 5.5 이미지 생성

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --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"
}'

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 <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())

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 <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example_seedream55"
    }
  ]
}

POST

images

generations

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --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"
}'

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 <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())

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 <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_example_seedream55"
    }
  ]
}

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --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"
}'

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 <token>"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())

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 <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(payload)
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

{
  "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장	선택

인증

string

필수

Authorization: Bearer <token>을 사용합니다. <token>은 APIMart API Key입니다.

요청 매개변수

string

필수

seedream-5-5를 지정합니다.

string

텍스트 및 이미지 기반 생성에서는 필수입니다. 레이어 분해에서는 생략하면 피사체, 텍스트, 배경을 자동 식별합니다. 분리할 요소를 프롬프트로 지정할 수도 있습니다.

string[]

일반 생성은 참조 이미지 최대 10장, 분해는 정확히 1장입니다. 공개 이미지 URL 또는 이미지 Base64 Data URI를 지원합니다. 로컬 파일은 이미지 업로드 API로 업로드한 뒤 반환된 url을 전달합니다.참조 이미지는 공개 접근 가능한 http(s) URL 또는 data:image/<format>;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로 전달하세요.

string

일반 생성 기본값은 2K이며 해상도 등급, 종횡비, 정확한 픽셀 크기를 지원합니다. 레이어 분해 기본값은 auto이며 1K / 1.5K / 2K / auto만 지원합니다.이미지 생성에서 size: "auto"는 2K와 같습니다. 비율 형식에서 resolution을 생략해도 2K를 사용합니다. 정확한 픽셀 지정 시 resolution을 보내지 말고 너비와 높이를 양의 정수로 지정하세요.

string

일반 생성은 종횡비 형식의 size와 함께 1K / 1.5K / 2K를 사용합니다. 분해에서는 플랫폼이 제공하는 size의 별칭입니다. size가 우선하며 생략한 경우에만 resolution을 사용하고, 둘 다 없으면 auto입니다. 분해는 1K / 1.5K / 2K / auto만 허용하며 비율이나 픽셀 표기는 동기 HTTP 400을 반환합니다. 3K / 4K는 지원하지 않습니다.

string

일반 생성은 auto(기본값), transparent, opaque를 지원합니다. 텍스트 및 이미지 기반 생성 모두 투명 배경을 지원합니다. 투명 배경은 PNG만 가능하며 output_format: "jpeg"와 함께 사용할 수 없습니다. 분해에서는 auto를 포함해 이 필드를 생략해야 합니다.

string

기본값:"png"

png(기본값) 또는 jpeg. 분해에서는 기본 이미지에만 적용되며 분리된 레이어는 항상 투명 PNG입니다.

integer

1만 허용합니다. 일반 생성은 요청당 1장을 출력하며, 분해 개수는 layer_decomposition_options.max_images로 조절합니다.

boolean

기본값:"false"

워터마크 추가 여부를 정하는 선택 항목입니다.

object

{"mode":"standard"}만 지원합니다. 생략해도 업스트림 기본값인 standard가 활성화되며 Seedream 5.5에서는 최적화를 끌 수 없습니다. disabled / none / off는 업스트림에서 HTTP 400 및 must be one of: standard로 거부합니다. fast는 플랫폼 접수 단계에서 즉시 HTTP 400을 반환합니다.

boolean

true이면 기본 이미지와 투명 레이어로 분해합니다. 입력은 정확히 1장이어야 하며 background를 전달할 수 없습니다. output_format은 기본 이미지에만 적용됩니다.

object

layer_decomposition: true에서만 허용합니다. 그 외에는 HTTP 400을 반환합니다.

표시 요청 매개변수

integer

기본값:"30"

2~100의 정수이며 기본값은 30입니다. 기본 이미지를 포함한 총 출력 상한으로, 지정한 수만큼 생성을 보장하지는 않습니다.

boolean

기본값:"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로 축소합니다.

요청 예시

이미지 편집 및 참조 융합

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --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을 접근 가능한 주소로 바꾸세요.

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --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를 사용합니다. 처음 30초는 3초 간격, 이후에는 5~10초 간격으로 조회하세요. 분해는 수분이 걸릴 수 있으며 서버 대기 상한은 13분입니다. task_id를 저장하고 종료 상태까지 조회하며 생성 요청을 중복 제출하지 마세요.

curl --request GET \
  --url 'https://api.apimart.ai/v1/tasks/task_example_seedream55' \
  --header 'Authorization: Bearer <token>'

data.status에서 pending / processing은 처리 중, completed는 성공입니다. failed이면 data.error.message를 확인하세요. 실패 비용은 자동 환불됩니다. 성공 이미지 URL은 data.result.images[].url[]에 있습니다.

결과 이미지는 3일 동안 보관되므로 빠르게 다운로드하세요. 작업 기록도 3일만 보관되며 이후에는 task_id로 조회할 수 없습니다.data.result.images[].expires_at은 현재 작업 완료 시각 + 24시간을 Unix 초 단위로 반환합니다. 실제 삭제보다 이른 보수적 표시이므로 실제 보관 기간이나 삭제 카운트다운 계산에 사용하지 마세요.

레이어 결과 및 OCR

아래는 구조를 설명하는 예시이며 실제 실행 기록이 아닙니다. 크기, 좌표, 텍스트는 예시 값입니다. 메타데이터는 없을 수 있으므로 선택 항목으로 처리하세요.

{
  "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 캔버스에는 정규화 좌표를 다음과 같이 변환합니다.

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장씩 계산하며 요청 구간을 모든 출력에 일괄 적용하지 않습니다. 실패 시 전액 환불합니다.

단가는 모델 요금을 확인하세요.

자주 발생하는 매개변수 오류

플랫폼 및 업스트림 검증 오류를 포함합니다. 제출 실패는 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`	전달 또는 플랫폼 내부 오류입니다. 반환된 설명에 따라 나중에 재시도하세요.

개요

모델

텍스트 시리즈

이미지 시리즈

비디오 시리즈

오디오 시리즈

모더레이션 시리즈

업로드 관리

작업 관리

계정 관리

Seedream 5.5 이미지 생성

모드

인증

요청 매개변수

크기 지정

레이어 분해 출력 크기

요청 예시

이미지 편집 및 참조 융합

레이어 분해 및 텍스트 OCR

작업 조회

레이어 결과 및 OCR

텍스트 인식 필드

과금

자주 발생하는 매개변수 오류

작업 실패 원인

​모드

​인증

​요청 매개변수

​크기 지정

​레이어 분해 출력 크기

​요청 예시

​이미지 편집 및 참조 융합

​레이어 분해 및 텍스트 OCR

​작업 조회

​레이어 결과 및 OCR

​텍스트 인식 필드

​과금

​자주 발생하는 매개변수 오류

​작업 실패 원인

모드

인증

요청 매개변수

크기 지정

레이어 분해 출력 크기

요청 예시

이미지 편집 및 참조 융합

레이어 분해 및 텍스트 OCR

작업 조회

레이어 결과 및 OCR

텍스트 인식 필드

과금

자주 발생하는 매개변수 오류

작업 실패 원인