메인 콘텐츠로 건너뛰기
POST

Authorizations

string
필수
모든 엔드포인트는 Bearer Token 인증이 필요합니다API 키 받기:API 키 관리 페이지 에서 API 키를 받으세요사용 시 요청 헤더에 다음을 추가:

Body

string
기본값:"mai-image-2.7"
필수
이미지 생성 모델 이름두 모델의 기능과 매개변수는 완전히 동일합니다.
boolean
기본값:"false"
이미지 작업을 제출하기 전에 콘텐츠 검토를 실행할지 여부를 지정합니다.
  • true: omni-moderation-latest로 프롬프트와 입력 이미지를 검토
  • false 또는 생략: 검토 요청을 보내지 않으며 검토 비용이나 지연이 추가되지 않음(기본값)
string
필수
이미지 생성을 위한 텍스트 설명 또는 편집 지시
  • 중국어와 영어를 지원하며, 자세하게 작성할 것을 권장합니다
  • 최대 20,000자, 초과 시 400 반환
  • 비어 있거나 공백만으로 구성될 수 없습니다
integer
기본값:"1"
생성할 이미지 수값: 1
요청당 1장만 생성할 수 있습니다. 여러 장이 필요하면 작업을 각각 제출하세요. 0, 음수 또는 1보다 큰 값을 전달하면 400을 반환합니다
string
기본값:"1:1"
이미지 화면비 또는 픽셀 크기, 텍스트로 이미지 생성 시에만 적용두 가지 형식을 지원합니다:
  • 화면비: 1:4부터 4:1 범위의 임의의 정수 비율(예: 1:1, 16:9, 9:16, 21:9). resolution과 함께 실제 픽셀을 결정합니다
  • 픽셀 크기: 너비x높이(너비*높이, 너비×높이도 허용), 예: 2048x1152. 이 경우 resolution은 무시됩니다
픽셀 크기 제약:
  • 너비와 높이 모두 768 이상
  • 너비 × 높이 4,194,304 이하(2048×2048)
  • 너비와 높이는 각각 32의 배수로 내림됩니다. 예를 들어 1000x1000은 실제로 992x992로 출력됩니다
예시: ✅ 2048x2048, 2048x1152, 2560x1536; ❌ 512x512(변 길이가 768 미만), 2080x2048(총 픽셀 수 초과)
auto는 지원하지 않으며, 전달하면 400을 반환합니다
string
기본값:"1K"
출력 해상도 등급, size가 화면비일 때만 적용선택 값: 1K / 2K(소문자 허용)size × resolution → 실제 픽셀 대응표:
4K는 지원하지 않으며, 다른 등급을 전달하면 400을 반환합니다. 짧은 변이 최소 768이어야 하므로 2:1보다 더 긴 비율은 1K 등급에서도 실제 픽셀이 약 100만을 넘습니다.
integer
정확한 픽셀 너비, height와 반드시 함께 전달해야 합니다
  • 우선순위가 가장 높으며, 함께 전달하면 size와 resolution을 덮어씁니다
  • 제약은 size 픽셀 크기와 동일: 너비와 높이 모두 768 이상, 총 픽셀 수 4,194,304 이하
  • 텍스트로 이미지 생성 시에만 적용
integer
정확한 픽셀 높이, width와 반드시 함께 전달해야 하며 제약은 width와 동일
array
참조 이미지 배열, 전달하면 이미지로 이미지 생성 모드로 동작합니다
  • 1장을 전달하면 단일 이미지 편집, 여러 장을 전달하면 다중 이미지 합성
string
배경 유형선택 값: auto / opaque, 전달하지 않은 경우와 결과가 같습니다
투명 배경 transparent는 아직 제공되지 않습니다. transparent 또는 기타 값을 전달하면 400을 반환합니다
auto_aspect_ratio: true, web_grounding: true는 지원하지 않으며, 전달하면 400을 반환합니다. quality, style, output_format, response_format, mask_url은 지원하지 않으며 무시됩니다. 출력은 PNG로 고정됩니다.

사용 시나리오 예시

텍스트로 이미지 생성(최소 요청) 기본값은 1:1 + 1K이며, 1024×1024를 출력합니다.
텍스트로 이미지 생성(화면비 + 2K 지정)
텍스트로 이미지 생성(정확한 픽셀)
단일 이미지 편집
다중 이미지 합성(URL + base64 혼합)

Response

integer
응답 상태 코드
array
응답 데이터 배열

작업 결과 조회

제출 성공 후 task_id 가 반환됩니다. GET /v1/tasks/{task_id} 로 작업 상태를 폴링하세요. 자세한 내용은 작업 조회 API 참조. 3–5초 간격으로 폴링하고 전체 제한 시간은 3분으로 설정하는 것을 권장합니다.

성공 응답 예시

이미지 가져오기: data.result.images[0].url[0]. 이미지 링크는 expires_at 이후 만료되므로 가능한 한 빨리 다운로드하여 저장하세요.

작업 상태