> ## 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.0-Flash 이미지 생성

>  - 비동기 처리 모드, 후속 조회를 위한 작업 ID 반환
- 텍스트-이미지, 단일 이미지-이미지, 다중 참조 이미지-이미지 생성 지원 (최대 10장의 참조 이미지)
- 1K / 1.5K / 2K 해상도 단계 또는 `size`로 정확한 픽셀 지정
- 단일 이미지 모델: 요청당 1장만 생성; PNG / JPEG 출력
- 생성된 이미지 링크는 72시간 동안 유효합니다. 빠르게 저장해 주세요 

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "seedream-5-0-flash",
      "prompt": "사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인",
      "size": "16:9",
      "resolution": "2K"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "seedream-5-0-flash",
      "prompt": "사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인",
      "size": "16:9",
      "resolution": "2K"
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "seedream-5-0-flash",
    prompt: "사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인",
    size: "16:9",
    resolution: "2K"
  };

  const headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
  })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io/ioutil"
      "net/http"
  )

  func main() {
      url := "https://api.apimart.ai/v1/images/generations"

      payload := map[string]interface{}{
          "model":      "seedream-5-0-flash",
          "prompt":     "사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인",
          "size":       "16:9",
          "resolution": "2K",
      }

      jsonData, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer <token>")
      req.Header.Set("Content-Type", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      body, _ := ioutil.ReadAll(resp.Body)
      fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.net.URI;

  public class Main {
      public static void main(String[] args) throws Exception {
          String url = "https://api.apimart.ai/v1/images/generations";

          String payload = """
          {
            "model": "seedream-5-0-flash",
            "prompt": "사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인",
            "size": "16:9",
            "resolution": "2K"
          }
          """;

          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(url))
              .header("Authorization", "Bearer <token>")
              .header("Content-Type", "application/json")
              .POST(HttpRequest.BodyPublishers.ofString(payload))
              .build();

          HttpResponse<String> response = client.send(request,
              HttpResponse.BodyHandlers.ofString());

          System.out.println(response.body());
      }
  }
  ```

  ```php PHP theme={null}
  <?php

  $url = "https://api.apimart.ai/v1/images/generations";

  $payload = [
      "model" => "seedream-5-0-flash",
      "prompt" => "사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인",
      "size" => "16:9",
      "resolution" => "2K"
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer <token>",
      "Content-Type: application/json"
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  echo $response;
  ?>
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'json'
  require 'uri'

  url = URI("https://api.apimart.ai/v1/images/generations")

  payload = {
    model: "seedream-5-0-flash",
    prompt: "사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인",
    size: "16:9",
    resolution: "2K"
  }

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(url)
  request["Authorization"] = "Bearer <token>"
  request["Content-Type"] = "application/json"
  request.body = payload.to_json

  response = http.request(request)
  puts response.body
  ```

  ```swift Swift theme={null}
  import Foundation

  let url = URL(string: "https://api.apimart.ai/v1/images/generations")!

  let payload: [String: Any] = [
      "model": "seedream-5-0-flash",
      "prompt": "사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인",
      "size": "16:9",
      "resolution": "2K"
  ]

  var request = URLRequest(url: url)
  request.httpMethod = "POST"
  request.setValue("Bearer <token>", forHTTPHeaderField: "Authorization")
  request.setValue("application/json", forHTTPHeaderField: "Content-Type")
  request.httpBody = try? JSONSerialization.data(withJSONObject: payload)

  let task = URLSession.shared.dataTask(with: request) { data, response, error in
      if let error = error {
          print("Error: \(error)")
          return
      }

      if let data = data, let responseString = String(data: data, encoding: .utf8) {
          print(responseString)
      }
  }

  task.resume()
  ```

  ```csharp C# theme={null}
  using System;
  using System.Net.Http;
  using System.Text;
  using System.Threading.Tasks;

  class Program
  {
      static async Task Main(string[] args)
      {
          var url = "https://api.apimart.ai/v1/images/generations";

          var payload = @"{
              ""model"": ""seedream-5-0-flash"",
              ""prompt"": ""사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인"",
              ""size"": ""16:9"",
              ""resolution"": ""2K""
          }";

          using var client = new HttpClient();
          client.DefaultRequestHeaders.Add("Authorization", "Bearer <token>");

          var content = new StringContent(payload, Encoding.UTF8, "application/json");
          var response = await client.PostAsync(url, content);
          var result = await response.Content.ReadAsStringAsync();

          Console.WriteLine(result);
      }
  }
  ```

  ```c C theme={null}
  #include <stdio.h>
  #include <curl/curl.h>

  int main(void) {
      CURL *curl;
      CURLcode res;

      curl_global_init(CURL_GLOBAL_DEFAULT);
      curl = curl_easy_init();

      if(curl) {
          const char *url = "https://api.apimart.ai/v1/images/generations";
          const char *payload = "{"
              "\"model\":\"seedream-5-0-flash\","
              "\"prompt\":\"사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인\","
              "\"size\":\"16:9\","
              "\"resolution\":\"2K\""
          "}";

          struct curl_slist *headers = NULL;
          headers = curl_slist_append(headers, "Authorization: Bearer <token>");
          headers = curl_slist_append(headers, "Content-Type: application/json");

          curl_easy_setopt(curl, CURLOPT_URL, url);
          curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
          curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

          res = curl_easy_perform(curl);

          if(res != CURLE_OK) {
              fprintf(stderr, "curl_easy_perform() failed: %s\n",
                      curl_easy_strerror(res));
          }

          curl_slist_free_all(headers);
          curl_easy_cleanup(curl);
      }

      curl_global_cleanup();
      return 0;
  }
  ```

  ```objectivec Objective-C theme={null}
  #import <Foundation/Foundation.h>

  int main(int argc, const char * argv[]) {
      @autoreleasepool {
          NSURL *url = [NSURL URLWithString:@"https://api.apimart.ai/v1/images/generations"];

          NSDictionary *payload = @{
              @"model": @"seedream-5-0-flash",
              @"prompt": @"사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인",
              @"size": @"16:9",
              @"resolution": @"2K"
          };

          NSError *error;
          NSData *jsonData = [NSJSONSerialization dataWithJSONObject:payload
                                                            options:0
                                                              error:&error];

          NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:url];
          [request setHTTPMethod:@"POST"];
          [request setValue:@"Bearer <token>" forHTTPHeaderField:@"Authorization"];
          [request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
          [request setHTTPBody:jsonData];

          NSURLSessionDataTask *task = [[NSURLSession sharedSession]
              dataTaskWithRequest:request
              completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                  if (error) {
                      NSLog(@"Error: %@", error);
                      return;
                  }
                  NSString *result = [[NSString alloc] initWithData:data
                                                          encoding:NSUTF8StringEncoding];
                  NSLog(@"%@", result);
              }];

          [task resume];
          [[NSRunLoop mainRunLoop] run];
      }
      return 0;
  }
  ```

  ```ocaml OCaml theme={null}
  (* Requires cohttp and yojson libraries *)
  open Lwt
  open Cohttp
  open Cohttp_lwt_unix

  let url = "https://api.apimart.ai/v1/images/generations"

  let payload = {|{
    "model": "seedream-5-0-flash",
    "prompt": "사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인",
    "size": "16:9",
    "resolution": "2K"
  }|}

  let () =
    let headers = Header.init ()
      |> fun h -> Header.add h "Authorization" "Bearer <token>"
      |> fun h -> Header.add h "Content-Type" "application/json"
    in
    let body = Cohttp_lwt.Body.of_string payload in

    let response = Client.post ~headers ~body (Uri.of_string url) >>= fun (resp, body) ->
      body |> Cohttp_lwt.Body.to_string >|= fun body_str ->
      print_endline body_str
    in
    Lwt_main.run response
  ```

  ```dart Dart theme={null}
  import 'dart:convert';
  import 'package:http/http.dart' as http;

  void main() async {
    final url = Uri.parse('https://api.apimart.ai/v1/images/generations');

    final payload = {
      'model': 'seedream-5-0-flash',
      'prompt': '사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인',
      'size': '16:9',
      'resolution': '2K'
    };

    final response = await http.post(
      url,
      headers: {
        'Authorization': 'Bearer <token>',
        'Content-Type': 'application/json',
      },
      body: jsonEncode(payload),
    );

    print(response.body);
  }
  ```

  ```r R theme={null}
  library(httr)
  library(jsonlite)

  url <- "https://api.apimart.ai/v1/images/generations"

  payload <- list(
    model = "seedream-5-0-flash",
    prompt = "사이버펑크 스타일의 도시 야경, 젖은 거리에 반사되는 네온사인",
    size = "16:9",
    resolution = "2K"
  )

  response <- POST(
    url,
    add_headers(
      Authorization = "Bearer <token>",
      `Content-Type` = "application/json"
    ),
    body = toJSON(payload, auto_unbox = TRUE),
    encode = "raw"
  )

  cat(content(response, "text"))
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01K8SGYNNNVBQTXNR4MM964S7K"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "잘못된 요청 매개변수",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "인증에 실패했습니다. API 키를 확인하세요",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "잔액이 부족합니다. 충전 후 다시 시도하세요",
      "type": "payment_required"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "error": {
      "code": 403,
      "message": "접근이 금지되었습니다. 이 리소스에 접근할 권한이 없습니다",
      "type": "permission_error"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "요청이 너무 많습니다. 잠시 후 다시 시도하세요",
      "type": "rate_limit_error"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "code": 500,
      "message": "서버 내부 오류. 나중에 다시 시도하세요",
      "type": "server_error"
    }
  }
  ```

  ```json 502 theme={null}
  {
    "error": {
      "code": 502,
      "message": "불량 게이트웨이입니다. 서버가 일시적으로 사용할 수 없습니다",
      "type": "bad_gateway"
    }
  }
  ```
</ResponseExample>

## 인증

<ParamField header="Authorization" type="string" required>
  모든 API 엔드포인트는 Bearer Token 인증이 필요합니다

  API 키 받기:

  [API 키 관리 페이지](https://apimart.ai/keys)를 방문하여 API 키를 받으세요

  요청 헤더에 추가:

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

<Info>
  **단일 이미지 모델**: `seedream-5-0-flash`는 요청당 1장의 이미지만 생성합니다(레이어 분해 제외). 다음 매개변수는 **거부**됩니다(HTTP 400, 작업 미생성, 비용 미청구):

  * `n > 1`
  * `sequential_image_generation`(그룹 생성 미지원)
  * `stream`(스트리밍 미지원)
  * `tools`(웹 검색 미지원)
  * `image_urls`가 10개를 초과
</Info>

<CardGroup cols={2}>
  <Card title="인터랙티브 편집" icon="crosshairs">
    프롬프트에 `<point>` / `<bbox>` 좌표를 사용하거나 손으로 표시한 이미지를 업로드하여 편집 위치를 정확하게 지정합니다.

    * 점 좌표: `<point>x y</point>` (하나의 점을 지정하며 영향 범위는 모델이 판단합니다)
    * 경계 상자 좌표: `<bbox>x1 y1 x2 y2</bbox>` (왼쪽 위와 오른쪽 아래 좌표를 지정하여 편집 영역의 크기를 정밀하게 제어합니다)
  </Card>

  <Card title="레이어 분해" icon="layer-group">
    하나의 이미지를 베이스 이미지와 최대 16개의 투명 PNG 레이어로 분리하고 위치와 쌓임 순서 정보를 반환합니다.
  </Card>
</CardGroup>

## Body

<ParamField body="model" type="string" default="seedream-5-0-flash" required>
  이미지 생성 모델 이름

  * `seedream-5-0-flash` (권장)
  * 허용 별칭: `seedream-5.0-pro`
</ParamField>

<ParamField body="nsfw_check" type="boolean" default="false">
  이미지 작업을 제출하기 전에 콘텐츠 검토를 실행할지 여부를 지정합니다.

  * `true`: `omni-moderation-latest`로 프롬프트와 입력 이미지를 검토
  * `false` 또는 생략: 검토 요청을 보내지 않으며 검토 비용이나 지연이 추가되지 않음(기본값)
</ParamField>

<ParamField body="prompt" type="string" required>
  이미지 생성을 위한 텍스트 설명

  `layer_decomposition: true`인 경우 선택 사항입니다. 생략하면 모델이 이미지의 주요 요소를 자동으로 인식하고 분리합니다.

  중국어와 영어 외에 러시아어, 아랍어, 필리핀어, 태국어, 터키어, 한국어, 말레이어, 스페인어, 포르투갈어, 인도네시아어, 프랑스어, 독일어, 베트남어, 일본어의 네이티브 텍스트 생성을 지원합니다.

  > **팁:** 영어 600단어 이내로 유지하세요. 설명이 너무 길면 세부 사항이 손실될 수 있습니다.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  해상도 등급(소문자 허용). 등급을 `size`에 직접 입력하는 것과 동일한 API Mart 확장 필드입니다.

  * `1K` (기본값)
  * `1.5K` (1K와 동일 가격, 더 나은 품질 — 특별한 이유가 없으면 1.5K 권장)
  * `2K`

  3K / 4K 등 미지원 단계는 400을 반환합니다.

  등급 형식의 `size`와 `resolution`을 모두 제공하면 `size`가 우선합니다.

  <Warning>
    `size`가 **정확한 픽셀 값**(예: `2048x1024`)이면 이 필드는 **무시**되며 치수는 `size`만으로 결정됩니다.
  </Warning>
</ParamField>

<ParamField body="size" type="string" default="auto">
  등급 키워드, 화면비, `auto` 또는 **정확한 픽셀 크기**.

  ### 형식 ①: 해상도 등급(권장)

  등급을 `size`에 직접 입력하거나 API Mart 확장 필드 `resolution`으로 제공할 수 있습니다:

  ```json theme={null}
  { "size": "2K" }
  ```

  ```json theme={null}
  { "resolution": "2K" }
  ```

  두 형식은 동일합니다. 등급만 지정할 때는 프롬프트에 원하는 레이아웃(예: "세로형 포스터", "가로형 커버")을 설명하고 모델이 화면비를 선택하게 하십시오.

  ### 형식 ②: 등급 + 화면비

  `resolution`과 함께 사용. 지원 비율:

  * `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `3:2`, `2:3`, `2:1`, `1:2`, `21:9`
  * `16x9` 형태의 `x` 구분도 허용
  * `2x1`은 `2:1`, `1x2`는 `1:2`와 같습니다. `x`는 소문자여야 하며 공백은 허용되지 않습니다.
  * `auto` (기본값): 해상도 단계만 적용; 최종 종횡비는 prompt / 참조 이미지에서 결정

  목록 밖의 비율(예: `9:21`)은 400 — **1:1로 조용히 대체되지 않음**.

  **단계 × 비율 → 출력 픽셀:**

  | 해상도      | 1:1       | 4:3       | 3:4       | 16:9      | 9:16      | 3:2       | 2:3       | 2:1       | 1:2       | 21:9      |
  | -------- | --------- | --------- | --------- | --------- | --------- | --------- | --------- | --------- | --------- | --------- |
  | **1K**   | 1024×1024 | 1152×864  | 864×1152  | 1312×736  | 736×1312  | 1248×832  | 832×1248  | 1440×720  | 720×1440  | 1568×672  |
  | **1.5K** | 1536×1536 | 1792×1344 | 1344×1792 | 2048×1152 | 1152×2048 | 1872×1248 | 1248×1872 | 2176×1088 | 1088×2176 | 2352×1008 |
  | **2K**   | 2048×2048 | 2304×1728 | 1728×2304 | 2560×1440 | 1440×2560 | 2496×1664 | 1664×2496 | 2880×1440 | 1440×2880 | 3024×1296 |

  ```json theme={null}
  { "resolution": "2K", "size": "2:1" }
  ```

  ### 형식 ③: 정확한 픽셀

  `size`가 `widthxheight`이면 픽셀이 그대로 사용되고 `resolution`은 적용되지 않습니다. `2048X1024` / `2048×1024` 허용.

  | 제약             | 범위                                                       |
  | -------------- | -------------------------------------------------------- |
  | 총 픽셀 (너비 × 높이) | `[921600, 4624220]` (약 `1280×720` \~ `2048×2048×1.1025`) |
  | 종횡비 (너비 / 높이)  | `[1/16, 16]`                                             |

  <Warning>
    제한은 너비와 높이의 **곱**에 적용되며, 각 변 단독이 아닙니다. 예: `512×512`는 너무 작음(400); `2048×1024`는 유효.
  </Warning>
</ParamField>

<ParamField body="background" type="string" default="opaque">
  출력 배경 모드:

  * `opaque`: 불투명 배경(기본값)
  * `transparent`: 투명 배경

  `transparent`는 알파 채널이 이미 있는 입력 이미지 1장을 사용하는 이미지-이미지 요청에서만 사용할 수 있으며 `output_format: "png"`도 필요합니다.
</ParamField>

<ParamField body="layer_decomposition" type="boolean" default="false">
  이미지를 레이어로 분해할지 여부입니다. 활성화하면 모델이 베이스 이미지 1장과 최대 16개의 알파 채널 PNG 레이어를 반환합니다.

  PNG 또는 JPEG 이미지 1장이 필요합니다. 총 픽셀 수는 `[262144, 36000000]`, 파일 크기는 30 MB 이하여야 합니다. `size`는 `1K`, `1.5K`, `2K`, `auto`만 허용하며 기본값은 `auto`입니다. `output_format`은 베이스 이미지 형식만 제어하고, 분해된 레이어는 항상 PNG입니다.
</ParamField>

<ParamField body="optimize_prompt_options" type="object" default={'{"mode":"standard"}'}>
  프롬프트 최적화 모드:

  * `standard`: 더 나은 품질의 표준 모드(기본값)

  평면 형식 `"optimize_prompt_options.mode": "standard"`도 허용됩니다.
</ParamField>

<ParamField body="n" type="integer" default="1">
  생성할 이미지 수입니다. `1`만 지원하며, 그룹 이미지 생성에는 `seedream-5-0-lite`를 사용하십시오.
</ParamField>

<ParamField body="image_urls" type="array">
  참조 이미지 URL 목록. 단일 / 다중 참조 image-to-image용, **최대 10장**

  두 가지 형식:

  **1. 공개 URL**

  * `http://` 또는 `https://`
  * 예: `https://example.com/image.jpg`

  **2. Base64 (Data URI)**

  * 형식: `data:image/<format>;base64,<data>` — `<format>`은 **소문자 필수**
  * 예: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABg...`

  **이미지당 제한:**

  * 형식: jpeg / png / webp / bmp / tiff / gif / heic / heif
  * 종횡비 (w/h): `[1/16, 16]`
  * 각 변 > 14 px
  * 크기 ≤ 30 MB
  * 총 픽셀 ≤ `6000×6000` (36,000,000)

  > **요금:** 첫 번째 참조 이미지는 무료; 추가 이미지마다 고정 추가 요금.
</ParamField>

<ParamField body="output_format" type="string" default="jpeg">
  출력 이미지 형식

  * `jpeg` (기본값)
  * `png`

  > **호환:** `response_format`은 `output_format`과 동일; 기타 값은 `jpeg`로 처리.
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  오른쪽 하단에 "AI generated" 워터마크를 추가할지 여부

  * `true`: 워터마크 추가
  * `false`: 없음 (기본값)
</ParamField>

## 요청 예제

### 텍스트-이미지 (단계 + 비율)

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "사이버펑크 도시 야경, 젖은 거리에 비치는 네온",
  "resolution": "2K",
  "size": "2:1",
  "output_format": "png"
}
```

### 텍스트-이미지 (정확한 픽셀)

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "미니멀 이커머스 히어로 이미지, 흰 배경, 제품 중앙",
  "size": "1600x1600"
}
```

### 다중 참조

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "이미지 1의 의상을 이미지 2의 의상으로 교체",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/dress.jpg"
  ],
  "resolution": "2K",
  "size": "auto"
}
```

### 권장: 1.5K 동일 가격, 더 나은 품질

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "오후 햇살 속 창가의 귀여운 주황 고양이, 시네마틱",
  "resolution": "1.5K",
  "size": "16:9"
}
```

### 레이어 분해

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "image_urls": ["https://example.com/poster.png"],
  "layer_decomposition": true,
  "size": "2K"
}
```

`0–1000`으로 정규화된 `<bbox>` 좌표를 사용해 추출할 요소를 정확하게 지정할 수도 있습니다:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "이미지를 정확한 레이어로 분리해 줘. 텍스트 좌표는 <bbox>180 64 812 198</bbox>, 앵무새 좌표는 <bbox>347 305 642 997</bbox>야.",
  "image_urls": ["https://example.com/poster.png"],
  "layer_decomposition": true
}
```

### 인터랙티브 편집

이미지의 손그림 표시를 자연어로 설명합니다:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "스케치에 따라 이미지를 편집해 줘. 왼쪽 하단 표시 영역에 잡지 더미를, 오른쪽 표시 영역에 커피 한 잔을 추가해 줘. 모든 스케치 선을 제거하고 구도는 유지해 줘.",
  "image_urls": ["https://example.com/sketch.png"],
  "size": "2K",
  "output_format": "png"
}
```

또는 `<point>` / `<bbox>`로 위치를 정확하게 지정합니다:

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "이미지 1의 <bbox>179 283 796 986</bbox> 주체를 이미지 2의 <bbox>118 331 933 871</bbox> 위치에 배치해 줘.",
  "image_urls": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}
```

### 알파 채널 편집

```json theme={null}
{
  "model": "seedream-5-0-flash",
  "prompt": "투명 배경을 유지하면서 앵무새를 공작으로 바꿔 줘",
  "image_urls": ["https://cdn.example.com/images/layer.png"],
  "background": "transparent",
  "output_format": "png",
  "size": "2K"
}
```

## 전체 예시: 작업 제출 및 이미지 가져오기

다음 스크립트는 비동기 작업 제출, 상태 폴링, 실패 상태 처리, 최종 이미지 URL 읽기의 전체 흐름을 보여 줍니다. 실행 전 `YOUR_API_KEY`를 교체하십시오.

```python Python theme={null}
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.apimart.ai"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 1. 생성 작업 제출
create_response = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=headers,
    json={
        "model": "seedream-5-0-flash",
        "prompt": "엷은 아침 안개가 낀 수묵화 풍의 장난 수향",
        "resolution": "1.5K",
        "size": "16:9",
        "output_format": "png",
    },
    timeout=30,
)
create_response.raise_for_status()
task_id = create_response.json()["data"][0]["task_id"]
print(f"작업 제출 완료: {task_id}")

# 2. 작업 상태 폴링
while True:
    task_response = requests.get(
        f"{BASE_URL}/v1/tasks/{task_id}",
        headers=headers,
        timeout=30,
    )
    task_response.raise_for_status()
    task = task_response.json()
    status = task["status"]
    print(f"상태: {status}; 진행률: {task.get('progress', 0)}%")

    if status == "success":
        image = task["result"]["images"][0]
        print("이미지 URL:", image["url"][0])
        print("이미지 크기:", image["sizes"][0])
        print("이미지 형식:", image["output_formats"][0])
        break

    if status in {"failed", "cancelled"}:
        raise RuntimeError(task.get("error", f"작업 {status}"))

    time.sleep(5)
```

성공하면 작업 조회 엔드포인트가 다음을 반환합니다:

```json theme={null}
{
  "id": "task_01JFXYZ123456789ABCDEF",
  "status": "success",
  "progress": 100,
  "cost": 0.045,
  "result": {
    "images": [
      {
        "url": ["https://cdn.example.com/images/image_task_xxx_0.png"],
        "sizes": ["2048x1152"],
        "output_formats": ["png"],
        "expires_at": 1784696685
      }
    ]
  }
}
```

<Note>
  반환된 이미지는 플랫폼이 관리하는 저장소에 미러링됩니다. 그래도 즉시 다운로드하여 자체 시스템에 영구 저장하고, 결과 URL을 영구 저장소로 간주하지 마십시오.
</Note>

## 전체 cURL 시나리오

### 다중 이미지 합성(최대 10개 참조)

```bash theme={null}
curl -X POST "https://api.apimart.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-flash",
    "prompt": "이미지 1의 인물을 이미지 2의 장면에 배치하고 조명을 황혼으로 통일해 줘",
    "image_urls": [
      "https://example.com/person.jpg",
      "https://example.com/scene.jpg"
    ],
    "resolution": "1.5K",
    "size": "16:9",
    "output_format": "png"
  }'
```

### 정확한 픽셀, 프롬프트 최적화, 워터마크

```bash theme={null}
curl -X POST "https://api.apimart.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-flash",
    "prompt": "젖은 거리에 네온빛이 반사되는 사이버펑크 도시 스카이라인",
    "size": "2048x1024",
    "optimize_prompt_options": { "mode": "standard" },
    "watermark": true
  }'
```

### 투명 레이어를 분해하여 독립적으로 편집

먼저 원본 이미지를 분해합니다:

```bash theme={null}
curl -X POST "https://api.apimart.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-flash",
    "image_urls": ["https://example.com/poster.png"],
    "layer_decomposition": true,
    "size": "2K"
  }'
```

다음으로 투명 레이어의 URL을 가져와 독립적으로 편집합니다:

```bash theme={null}
curl -X POST "https://api.apimart.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-flash",
    "prompt": "이미지의 앵무새를 공작으로 바꿔 줘",
    "image_urls": ["https://cdn.example.com/images/image_task_xxx_4.png"],
    "background": "transparent",
    "output_format": "png",
    "size": "2K"
  }'
```

## 레이어 분해 응답 및 재구성

`url`, `sizes`, `output_formats`, `layers` 배열은 인덱스별로 서로 대응하며, 인덱스 `0`은 항상 베이스 이미지입니다:

```json theme={null}
{
  "result": {
    "images": [{
      "url": [
        "https://cdn.example.com/images/image_task_xxx_0.jpeg",
        "https://cdn.example.com/images/image_task_xxx_1.png",
        "https://cdn.example.com/images/image_task_xxx_2.png"
      ],
      "sizes": ["2048x2048", "1273x265", "492x98"],
      "output_formats": ["jpeg", "png", "png"],
      "layer_decomposition": true,
      "layers": [
        { "z_index": 0, "size": "2048x2048", "output_format": "jpeg" },
        {
          "z_index": 1,
          "size": "1273x265",
          "output_format": "png",
          "name": "제목 텍스트",
          "description": "세리프 체의 큰 노란색 제목 텍스트",
          "bounding_box": {
            "absolute": [383, 120, 1655, 384],
            "normalized": [187, 59, 808, 188]
          }
        },
        {
          "z_index": 2,
          "size": "492x98",
          "output_format": "png",
          "name": "왼쪽 상단 태그라인",
          "description": "흰색 2줄 영문 태그라인",
          "bounding_box": {
            "absolute": [140, 451, 631, 548],
            "normalized": [68, 220, 308, 268]
          }
        }
      ]
    }]
  }
}
```

`z_index` 오름차순으로 레이어를 합성합니다. 절대 좌표로 출력 베이스 이미지에 재구성하려면:

```text theme={null}
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
```

<Warning>
  레이어 분해는 이미지별로 과금됩니다. 작업 제출 시 최대 17장을 사전 승인합니다. 완료 후 각 출력을 실제 픽셀 수에 따라 등급 판정하여 개별 정산하고, 초과 사전 승인액은 자동 환불합니다. 잔액은 17장의 사전 승인을 충당해야 하며 `size: "auto"`는 2K 등급으로 사전 승인됩니다.
</Warning>

## 요금 안내

```
총액 = 출력 단가 + 참조 이미지 가산 × max(0, 참조 장수 − 1)
```

출력은 **실제 총 픽셀** 기준으로 구분합니다(약 2.61M = 2,601,124):

| 조건                                                                              | 단가              |
| ------------------------------------------------------------------------------- | --------------- |
| 총 픽셀 ≤ 2.61M (1.5K 이하: `resolution`이 `1K` / `1.5K` / 미지정, 또는 정확 픽셀 ≤ 2,601,124) | **\$0.045** / 장 |
| 총 픽셀 > 2.61M (1.5K 초과: `resolution: "2K"`, 또는 정확 픽셀 > 2,601,124)                | **\$0.09** / 장  |

* **1.5K는 1K와 동일 요금**(\$0.045).
* `size`가 정확 픽셀일 때 과금은 **실제 출력 면적** 기준이며 `resolution`은 영향을 주지 않습니다(예: `size: "2048x2048"` → \$0.09).
* 참조 이미지 1장은 무료, 2장부터 가산.
* 작업 실패 시 전액 자동 환불.

### 레이어 분해 사전 승인 및 정산

작업 제출 시 최종 레이어 수와 크기를 알 수 없으므로, 요청에 기반한 보수적 규칙으로 사전 승인합니다:

* 정확한 픽셀: 요청한 픽셀 면적으로 등급 판정.
* `1K` / `1.5K`: 1K 등급으로 사전 승인.
* `2K`: 2K 등급으로 사전 승인.
* `auto`: 최대 2K로 출력할 수 있으므로 2K 등급으로 사전 승인.

완료 후 베이스 이미지와 실제 각 레이어를 실제 픽셀 면적으로 **개별 등급 판정하여 합산**합니다. 초과 사전 승인액은 자동 환불됩니다. 레이어는 보통 베이스 이미지보다 훨씬 작으므로, 2K 등급으로 사전 승인된 작업도 최종적으로 전부 1K 등급으로 정산될 수 있습니다.

<Info>
  예: `1080×1080` 입력이 10장으로 분해되면 `17장 × 2K 등급`으로 사전 승인합니다. 최종 10장이 모두 261만 픽셀 이하라면 `10장 × 1K 등급`으로 정산하고 나머지 크레딧은 자동 환불합니다.
</Info>

## 자주 발생하는 오류

| 경우                         | 설명                                                                  |
| -------------------------- | ------------------------------------------------------------------- |
| 미지원 `resolution` 단계        | 예: 3K / 4K → 400                                                    |
| 지원하지 않는 `size` 값           | `1K` / `1.5K` / `2K` / `auto`, 지원하는 화면비, 유효한 픽셀 크기 중 어느 것도 아님 → 400 |
| 정확 픽셀 총량 범위 초과             | `[921600, 4624220]` 내여야 함                                           |
| 정확 픽셀 종횡비 범위 초과            | `[1/16, 16]` 내여야 함                                                  |
| `n > 1` / 그룹 이미지 매개변수      | 단일 이미지 모델이 거부                                                       |
| 참조 이미지 10장 초과              | Rejected                                                            |
| 이미지 없이 또는 여러 이미지로 레이어 분해   | 이미지 1장만 필요                                                          |
| 비율 또는 정확한 픽셀을 사용한 레이어 분해   | `size`는 `1K` / `1.5K` / `2K` / `auto`만 지원                           |
| 텍스트-이미지 또는 다중 입력에 투명 배경 사용 | 알파 채널이 있는 입력 이미지 1장만 필요                                             |
| JPEG와 투명 배경 사용             | `output_format: "png"` 설정                                           |
| `stream` / `tools`         | 이 모델에서 미지원, 400 반환                                                  |
| 잘못된 프롬프트 최적화 모드            | `standard`만 지원                                                      |

<Note>
  ⏱️ **느린 생성**: 1K는 약 90초, 2K는 약 160초(품질 우선). 5〜10초마다 [작업 상태 가져오기](/ko/api-reference/tasks/status)를 폴링하고 클라이언트 타임아웃을 **5분**으로 설정하십시오. 생성 결과를 즉시 저장하십시오.
</Note>

## 응답

<ResponseField name="code" type="integer">
  응답 상태 코드
</ResponseField>

<ResponseField name="data" type="array">
  응답 데이터 배열

  <Expandable title="속성">
    <ResponseField name="status" type="string">
      작업 상태

      * `submitted` - 제출됨
    </ResponseField>

    <ResponseField name="task_id" type="string">
      고유 작업 식별자
    </ResponseField>
  </Expandable>
</ResponseField>