메인 콘텐츠로 건너뛰기
POST
model: "kling-v4-image"를 지정하여 POST /v1/images/generations로 비동기 작업을 제출합니다. data[0].task_id를 얻은 후 GET /v1/tasks/{task_id}로 결과를 조회합니다.

인증

string
필수
Authorization: Bearer <token>을 사용합니다. <token>은 APIMart API 키입니다.

요청 매개변수

string
필수
kling-v4-image로 지정합니다.
boolean
기본값:"false"
이미지 작업을 제출하기 전에 콘텐츠 검토를 실행할지 여부를 지정합니다.
  • true: omni-moderation-latest로 프롬프트와 입력 이미지를 검토
  • false 또는 생략: 검토 요청을 보내지 않으며 검토 비용이나 지연이 추가되지 않음(기본값)
string
필수
텍스트 기반 생성, 이미지 기반 생성, 시리즈 생성 모두 필수입니다. 원하는 내용과 피하고 싶은 내용을 함께 작성할 수 있습니다. 영어만 사용하면 최대 50,000자, 중국어 등만 사용하면 최대 21,000자이며 혼합 언어는 비율에 따라 계산됩니다.
string[]
공개적으로 접근 가능한 이미지 직접 URL을 최대 10개 지정합니다. 로컬 파일은 이미지 업로드 API로 업로드한 후 반환된 url을 사용하세요.JPG / JPEG / PNG / GIF를 지원합니다. 이미지당 최대 30 MB, 너비와 높이 모두 최소 300 px, 가로세로 비율은 2:5–5:2여야 합니다.제출 시 참조 이미지를 검사합니다. URL이 HTTP 403 / 404 / 410을 반환하거나, 어느 한 변이 300 px 미만이거나, 비율이 2:5–5:2를 벗어나거나, 이미지가 30 MB를 초과하면 즉시 HTTP 400을 반환합니다. 작업은 생성되지 않고 생성 요금도 부과되지 않습니다. 원본 서버 시간 초과 등 다른 가져오기 오류는 먼저 접수된 후 작업이 실패하며 선차감한 생성 요금이 전액 환불됩니다.프롬프트에서 @Image1, @Image2 등으로 배열 순서에 따라 이미지를 참조할 수 있습니다. 이 표기가 없어도 입력 이미지를 참조합니다.
integer
기본값:"1"
일반 모드의 출력 수로, 1–9 사이의 정수이며 기본값은 1입니다. 시리즈 모드에서는 n을 생략하거나 1로 설정할 수 있으며 출력 수는 sequential_image_generation_options.max_images로 지정합니다. 시리즈에서 n > 1이면 HTTP 400을 반환합니다.
string
기본값:"2K"
2K(기본값), 4K, 8K를 지원하며 대소문자를 구분하지 않습니다. 출력 형식은 PNG입니다. 1:1 비율에서 2K는 2048×2048, 4K는 4096×4096, 8K는 8192×8192입니다. 다른 비율은 반환된 이미지의 실제 크기를 확인하세요.8K에서도 텍스트 기반 생성, 이미지 기반 생성, 시리즈 생성을 지원합니다. 일반 모드는 1–9장, 시리즈는 2–4장, 참조 이미지는 최대 10장입니다. 참조 이미지의 형식, 크기 조건, 장당 30 MB 제한은 동일합니다.
string
기본값:"auto"
출력 가로세로 비율입니다. auto(기본값)와 다음 8가지 비율을 지원합니다.16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9.auto는 프롬프트나 참조 이미지에 따라 비율을 결정합니다. 2048x2048 같은 픽셀 크기는 지원하지 않습니다.
string
size의 별칭이며 허용 값은 동일합니다. 두 필드를 모두 전달하면 aspect_ratio가 우선합니다.
string
기본값:"disabled"
disabled 또는 생략 시 일반 생성입니다. auto로 설정하면 관련 이미지를 시리즈로 생성하며 sequential_image_generation_options.max_images가 필수입니다. 여기서 auto는 이미지 수를 자동 결정한다는 뜻이 아닙니다.
object
시리즈 모드의 이미지 수를 지정합니다.
width, height, mask_url, 픽셀 형식의 size, watermark: true는 지원하지 않으며 전달하면 HTTP 400을 반환합니다.

요청 예제

아래 요청은 POST /v1/images/generations로 보냅니다. 예제 이미지 URL을 실제 접근 가능한 직접 링크로 바꾸세요.

이미지 기반 생성

4K 이미지 3장 생성

8K 이미지 1장 생성

관련된 8K 이미지 4장 시리즈 생성

시리즈에서는 max_images를 2–4로 지정합니다. n은 생략하거나 1로 설정할 수 있지만 1보다 클 수 없습니다. 몇 분이 걸릴 수 있으므로 task_id를 보관하고 상태를 조회하여 중복 제출을 피하세요.

8K 출력 및 소요 시간 예시

다음은 테스트 환경에서 측정한 샘플입니다. 이미지 크기, 파일 크기, 소요 시간은 참고용이며 실제 결과는 달라질 수 있습니다. completed 또는 failed가 될 때까지 5–10초 간격으로 조회하세요. estimated_time은 60초로 고정되어 있으므로 실제 완료 예상 시간이나 카운트다운으로 사용하면 안 됩니다. task_id를 보관하고 대기 중에 중복 제출하지 마세요. 8K 결과는 PNG 원본이며 파일 하나가 100 MB를 넘을 수 있습니다. 목록과 미리보기에는 직접 만든 썸네일을 사용하거나 필요할 때 이미지를 불러오세요. 원본 다운로드 기능과 큰 파일 크기 안내를 제공하세요.

작업 조회

작업 조회 API의 data.status를 확인하세요. pending / processing은 처리 중, completed는 성공이며 failed이면 data.error.message를 확인합니다.
아래는 성공 결과의 구조 예시입니다. 이미지 URL은 data.result.images[].url[]에 있으며 url은 배열입니다. 모든 출력을 순회하여 가져온 후 바로 다운로드해 보관하세요.

요금

실제 출력 이미지 수와 선택한 해상도 등급에 따라 요금이 부과되며, 참조 이미지는 장당 별도로 계산됩니다. 단가는 가격 페이지를 확인하세요.
  • 일반 생성에서 n=3이면 출력 3장으로, 시리즈는 실제 반환된 장수로 계산합니다.
  • 참조 이미지는 요청당 각 1회만 계산하며 출력 장수를 곱하지 않습니다. 참조 2장으로 3장을 생성하면 입력 2장과 출력 3장 요금입니다.
  • 생성에 실패한 작업에는 생성 요금이 부과되지 않으며 선차감한 생성 요금은 전액 환불됩니다.

주요 매개변수 오류

아래 매개변수 오류는 제출 시 동기적으로 HTTP 400을 반환하며 작업이 생성되지 않고 생성 요금도 부과되지 않습니다. 제출 오류는 error.message, 작업 생성 후 실패는 data.error.message를 확인하세요.