> ## 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시간 동안 유효합니다. 빠르게 저장해 주세요 

```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"))
```

```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"
  }
}
```

## 인증

**Authorization** `string` *required*

모든 API 엔드포인트는 Bearer Token 인증이 필요합니다

API 키 받기:

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

요청 헤더에 추가:

```
Authorization: Bearer YOUR_API_KEY
```

> [!NOTE]
>
> **단일 이미지 모델**: `seedream-5-0-flash`는 요청당 1장의 이미지만 생성합니다(레이어 분해 제외). 다음 매개변수는 **거부**됩니다(HTTP 400, 작업 미생성, 비용 미청구):
>
> * `n > 1`
> * `sequential_image_generation`(그룹 생성 미지원)
> * `stream`(스트리밍 미지원)
> * `tools`(웹 검색 미지원)
> * `image_urls`가 10개를 초과

> [card] 인터랙티브 편집
>
> 프롬프트에 `<point>` / `<bbox>` 좌표를 사용하거나 손으로 표시한 이미지를 업로드하여 편집 위치를 정확하게 지정합니다.
>
> * 점 좌표: `<point>x y</point>` (하나의 점을 지정하며 영향 범위는 모델이 판단합니다)
> * 경계 상자 좌표: `<bbox>x1 y1 x2 y2</bbox>` (왼쪽 위와 오른쪽 아래 좌표를 지정하여 편집 영역의 크기를 정밀하게 제어합니다)

> [card] 레이어 분해
>
> 하나의 이미지를 베이스 이미지와 최대 16개의 투명 PNG 레이어로 분리하고 위치와 쌓임 순서 정보를 반환합니다.

## Body

**model** `string` *required* (default: seedream-5-0-flash)

이미지 생성 모델 이름

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

**nsfw\_check** `boolean` (default: false)

이미지 작업을 제출하기 전에 콘텐츠 검토를 실행할지 여부를 지정합니다.

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

**prompt** `string` *required*

이미지 생성을 위한 텍스트 설명

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

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

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

**resolution** `string` (default: 1K)

해상도 등급(소문자 허용). 등급을 `size`에 직접 입력하는 것과 동일한 API Mart 확장 필드입니다.

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

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

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

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

**size** `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`는 유효.

**background** `string` (default: opaque)

출력 배경 모드:

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

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

**layer\_decomposition** `boolean` (default: false)

이미지를 레이어로 분해할지 여부입니다. 활성화하면 모델이 베이스 이미지 1장과 최대 16개의 알파 채널 PNG 레이어를 반환합니다.

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

**optimize\_prompt\_options** `object` (default: \{"mode":"standard"})

프롬프트 최적화 모드:

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

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

**n** `integer` (default: 1)

생성할 이미지 수입니다. `1`만 지원하며, 그룹 이미지 생성에는 `seedream-5-0-lite`를 사용하십시오.

**image\_urls** `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)

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

**output\_format** `string` (default: jpeg)

출력 이미지 형식

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

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

**watermark** `boolean` (default: false)

오른쪽 하단에 "AI generated" 워터마크를 추가할지 여부

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

## 요청 예제

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

```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을 영구 저장소로 간주하지 마십시오.

## 전체 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 등급으로 사전 승인됩니다.

## 요금 안내

```
총액 = 출력 단가 + 참조 이미지 가산 × 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 등급으로 정산될 수 있습니다.

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

## 자주 발생하는 오류

| 경우 | 설명 |
| - | - |
| 미지원 `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초마다 [작업 상태 가져오기](https://docs.apimart.ai/ko/api-reference/tasks/status.md)를 폴링하고 클라이언트 타임아웃을 **5분**으로 설정하십시오. 생성 결과를 즉시 저장하십시오.

## 응답

**code** `integer`

응답 상태 코드

**data** `array`

응답 데이터 배열

**속성**

**status** `string`

작업 상태

* `submitted` - 제출됨

**task\_id** `string`

고유 작업 식별자


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.