> ## 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. # FLUX 3 Image 이미지 생성 > 텍스트 기반 이미지 생성, 단일 이미지 편집 및 최대 10장의 참조 이미지를 지원하며 다양한 화면비와 최대 4k 해상도를 제공합니다. 이 API는 비동기 방식입니다. 제출에 성공하면 `task_id`를 반환합니다. [작업 조회](/ko/api-reference/tasks/status)로 상태와 이미지를 가져오고, `completed` 또는 `failed`가 되면 폴링을 중지하세요. `4k` 생성은 몇 분이 걸릴 수 있으므로 전체 대기 제한 시간을 10분으로 설정하는 것을 권장합니다. ```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": "flux-3-image", "prompt": "새벽 안개에 덮인 해안 도로, 초광각 영화 장면, 헤드라이트를 켠 빈티지 자동차 한 대", "aspect_ratio": "21:9", "resolution": "2k" }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.apimart.ai/v1/images/generations", headers={"Authorization": "Bearer "}, json={ "model": "flux-3-image", "prompt": "새벽 안개에 덮인 해안 도로, 초광각 영화 장면, 헤드라이트를 켠 빈티지 자동차 한 대", "aspect_ratio": "21:9", "resolution": "2k" } ) 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" }, body: JSON.stringify({ model: "flux-3-image", prompt: "새벽 안개에 덮인 해안 도로, 초광각 영화 장면, 헤드라이트를 켠 빈티지 자동차 한 대", aspect_ratio: "21:9", resolution: "2k" }) }); console.log(await response.json()); ``` ```json 200 theme={null} { "code": 200, "data": [ { "status": "submitted", "task_id": "task_01K..." } ] } ``` ## 요청 헤더 `Bearer ` 형식의 Bearer 인증입니다. ``은 APIMart API Key입니다. ## 요청 매개변수 `flux-3-image`로 고정됩니다. 텍스트 기반 생성의 장면 설명 또는 이미지 편집 지시입니다. 네거티브 프롬프트는 지원하지 않으므로 원하는 장면을 긍정적으로 설명하세요. `prompt` 안의 태그와 bbox JSON으로 레이아웃 또는 부분 편집 영역을 지정할 수 있습니다. 아래 예시를 참고하세요. 참조 이미지 목록으로 최대 10장을 지원합니다. 공개적으로 접근 가능한 HTTP(S) URL 또는 Base64 입력을 지원합니다. 생략하면 텍스트 기반 생성입니다. 한 장을 제공하면 단일 이미지 편집, 여러 장을 제공하면 다중 이미지 참조에 사용할 수 있습니다. 출력 화면비입니다. 지원 값: `21:9`, `2:1`, `16:9`, `3:2`, `7:5`, `4:3`, `5:4`, `1:1`, `4:5`, `3:4`, `5:7`, `2:3`, `9:16`, `1:2`, `9:21` 또는 `auto`. `16x9` 형식의 비율 표기도 허용됩니다. `auto` 사용 시: * 편집 또는 다중 이미지 참조: 첫 번째 참조 이미지의 화면비를 따릅니다. * 텍스트 기반 생성: 프롬프트에 따라 결정하며, 화면비가 정해지지 않으면 `1:1`을 사용합니다. 화면비 호환 매개변수로 `aspect_ratio`를 대신할 수 있으며 같은 값을 사용합니다. 둘 중 하나만 사용하는 것을 권장합니다. `1024x1024` 같은 픽셀 크기는 지원하지 않으며 HTTP 400을 반환합니다. 출력 해상도는 `resolution`으로 선택하세요. 출력 해상도 등급입니다. `768sq`, `1k`, `1.5k`, `2k`, `4k`를 지원하며 대소문자를 구분하지 않습니다. `768`은 `768sq`와 같습니다. 이 매개변수는 과금 등급을 결정합니다. 생략하면 `1k`로 생성하고 과금합니다. `3k` 등 지원하지 않는 값은 HTTP 400을 반환합니다. 콘텐츠 안전 허용 수준입니다. 범위는 0–4이며 0이 가장 엄격합니다. 생성 전 웹 또는 이미지 검색을 허용할지 여부입니다. `false`로 비활성화할 수 있습니다. 불리언이어야 하며 문자열 `"false"` 또는 `"true"`를 전달하면 안 됩니다. 요청당 1장을 생성하며 `1`만 지원합니다. 여러 장이 필요하면 작업을 각각 제출하세요. 1보다 큰 값은 HTTP 400을 반환합니다. ## 지원하지 않는 매개변수 다음 매개변수를 전달하면 HTTP 400을 반환하며 조용히 무시되지 않습니다. * `width`, `height` * `1024x1024` 같은 픽셀 크기 형식의 `size` * `seed`, `steps`, `guidance` * `output_format`, `negative_prompt`, `prompt_upsampling`, `mask_url` 더 높은 해상도에는 `resolution`, 특정 화면비에는 `aspect_ratio`를 사용하세요. ## 참조 이미지 편집 ```json theme={null} { "model": "flux-3-image", "prompt": "이미지의 자동차를 빨간색으로 바꾸고 기존 도로, 배경, 조명은 유지해 주세요", "image_urls": ["https://example.com/car.jpg"], "aspect_ratio": "auto", "resolution": "2k" } ``` 예시 URL을 공개적으로 접근 가능한 이미지 URL로 바꾸세요. 다중 이미지 참조 시 `image_urls`에 여러 주소를 제공하되 총 10장을 넘지 않아야 합니다. ## 다중 이미지 참조 편집, 부분 편집, 레이아웃은 모두 이 페이지의 동일한 API와 모델을 사용하며 `resolution`에 따라 과금됩니다. 참조 이미지는 순서대로 첫 번째가 `ref_image_0`, 두 번째가 `ref_image_1`입니다. 프롬프트에서 `Image 1` / `Image 2`로 지칭할 수도 있습니다. ```json theme={null} { "model": "flux-3-image", "prompt": "Image 1을 Image 2의 스타일로 변환해 주세요.", "image_urls": [ "https://example.com/subject.jpg", "https://example.com/style.jpg" ], "aspect_ratio": "auto" } ``` ## 부분 편집(bounding box) `prompt` 앞부분에 자연어 편집 지시를 작성하고 `` 같은 `<태그>`로 요소를 지정하세요. 같은 문자열 뒤에 JSON 배열을 추가하며 각 객체는 하나의 상자를 설명합니다. bbox는 별도의 요청 매개변수가 아닙니다. | 필드 | 설명 | | - | - | | `id` | 프롬프트의 요소 태그와 대응하며 꺾쇠괄호는 포함하지 않습니다. | | `from` | 요소의 출처(예: `ref_image_0`). 새로 그리거나 다시 그릴 요소는 `null`을 사용합니다. | | `src_bbox` | 원본 이미지의 상자. `from`이 `null`이면 이 값도 `null`입니다. | | `tgt_bbox` | 출력 이미지의 상자. `src_bbox`와 같으면 제자리에 유지하고 다르면 이동합니다. | | `desc` | 요소를 어떻게 변경하거나 무엇을 유지할지 설명합니다. | 모든 상자 필드(`src_bbox`, `tgt_bbox`, `bbox`)는 `[위, 왼쪽, 아래, 오른쪽]`, 즉 `[y1, x1, y2, x2]`를 사용합니다. **0–1000 정규화 좌표**이며 왼쪽 위는 `[0,0]`, 오른쪽 아래는 `[1000,1000]`입니다. 실제 픽셀 좌표가 아닙니다. 아래 예시는 상자 안의 자동차를 빨간색으로 바꾸고 유지할 배경을 설명합니다. URL과 상자 위치는 예시이므로 실제 이미지에 맞게 바꾸세요. ```json theme={null} { "model": "flux-3-image", "prompt": "에서 자동차 을 빨간색으로 바꾸고 배경 은 유지해 주세요. [{\"id\":\"car_1\",\"from\":null,\"src_bbox\":null,\"tgt_bbox\":[250,300,750,800],\"desc\":\"원래 모양과 방향을 유지한 빨간 자동차.\"},{\"id\":\"background_1\",\"from\":\"ref_image_0\",\"src_bbox\":[0,0,1000,1000],\"tgt_bbox\":[0,0,1000,1000],\"desc\":\"원래 도로, 배경, 조명을 유지합니다.\"}]", "image_urls": [ "https://example.com/car.jpg" ], "aspect_ratio": "auto", "resolution": "2k" } ``` ### 요소 이동 다음 객체를 프롬프트 끝의 bbox 배열에 넣으세요. `from`은 원본 이미지, `src_bbox`는 원래 위치, `tgt_bbox`는 새 위치입니다. 자연어 지시에도 대응하는 `` 태그를 사용하세요. ```json theme={null} { "id": "knight_1", "from": "ref_image_0", "src_bbox": [ 500, 150, 850, 350 ], "tgt_bbox": [ 194, 55, 544, 255 ], "desc": "작은 회색 코바늘 기사 인형." } ``` ## 텍스트 기반 생성 레이아웃 참조 이미지 없이도 레이아웃을 지정할 수 있습니다. 각 상자는 `id`, `bbox`, `desc`를 사용합니다. 좌표 격자가 화면비에 따라 늘어나므로 `aspect_ratio`를 명시하세요. ```json theme={null} { "model": "flux-3-image", "aspect_ratio": "1:1", "prompt": "단색 연두색 배경 위에 검은색 달리는 인물 실루엣 이 있는 미니멀 일러스트. [{\"id\":\"background_1\",\"bbox\":[0,0,1000,1000],\"desc\":\"은은한 종이 질감이 있는 형광 연두색 배경.\"},{\"id\":\"silhouette_1\",\"bbox\":[150,150,850,850],\"desc\":\"점묘 질감의 검은색 달리는 인물 실루엣.\"}]" } ``` ### 사용 시 주의 * bbox JSON은 `prompt` 문자열의 일부입니다. 요청 JSON을 직접 작성할 때 내부 큰따옴표는 `\"`로 이스케이프해야 합니다. SDK 또는 JSON 직렬화 메서드를 사용하면 자동 처리할 수 있습니다. * 유지할 영역도 나열하고 `desc`에 유지 조건을 설명하세요. * 프롬프트의 요소 태그는 JSON의 `id`와 일대일로 대응해야 합니다. `` 같은 참조 식별자는 입력 이미지를 가리킵니다. * 이 모델에는 `mask` 매개변수가 없으며 `mask_url`도 지원하지 않습니다. `mask_url`을 전달하면 HTTP 400을 반환합니다. bbox 편집은 마스크 업로드 매개변수를 사용하지 않습니다. ## 제출 응답 응답 상태 코드입니다. 성공 시 `200`입니다. 작업 제출 결과입니다. 제출 성공 시 `submitted`이며 생성 완료를 의미하지 않습니다. 작업 상태와 결과 조회에 사용하는 작업 ID입니다. ## 작업 결과 조회 ```bash theme={null} curl --request GET \ --url https://api.apimart.ai/v1/tasks/task_01K... \ --header 'Authorization: Bearer ' ``` 성공 응답 예시(이미지 URL은 자리표시자입니다): ```json theme={null} { "code": 200, "data": { "status": "completed", "result": { "images": [ { "url": ["https://example.com/generated-image.jpg"] } ] } } } ``` `data.result.images[0].url` 배열에서 이미지 링크를 가져오세요. 작업 상태가 `failed`이면 반환된 오류를 확인하고 이미지를 계속 기다리지 마세요. ## 해상도 및 과금 이미지당 과금되며 단가는 `resolution`에 의해서만 결정됩니다. 화면비나 참조 이미지 수와는 관계없으며 참조 이미지에는 추가 요금이 없습니다. | 해상도 등급 | 대략적인 출력 크기 | | - | - | | `768sq` | 약 768×768 | | `1k`(기본값) | 약 1MP | | `1.5k` | 약 2MP | | `2k` | 약 4MP | | `4k` | 약 16MP | 출력 크기는 참고용 근사값이며 실제 픽셀 크기는 반환된 이미지를 기준으로 합니다. 등급별 가격은 [모델 가격](https://apimart.ai/pricing)을 확인하세요. 작업이 실패하거나 콘텐츠 검토에서 차단되면 전액 환불됩니다. ## 일반적인 매개변수 오류 | 요청 | 결과 및 해결 방법 | | - | - | | `resolution: "3k"` | HTTP 400. 지원하는 5가지 등급 중 하나 사용 | | `size: "1024x1024"` | HTTP 400. 화면비를 지정하고 `resolution`으로 해상도 선택 | | `n: 2` | HTTP 400. 요청당 1장만 생성 | | 참조 이미지 11장 | HTTP 400. 최대 10장 제공 | | `grounding: "false"` | HTTP 400. 불리언 `false` 사용 | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.