Skip to main content
POST
연결된 계정에 이미지를 생성합니다. 웹 앱과 동일한 미디어 허용량 및 보호 장치를 적용합니다. 반환된 generationId를 저장하고 images_download로 이미지를 조회하세요. 동일한 요청을 재시도할 때는 requestId를 재사용하세요.

인증 및 권한

string
필수
이 헤더에 VoiceCheap API 키를 전달하세요. 동일한 API 키를 사용하는 Authorization: Bearer도 지원합니다. OAuth 액세스 토큰은 MCP에서만 허용되며, 이 REST 엔드포인트에서는 사용할 수 없습니다.
필요한 권한: images:write. 활성 유료 구독이 필요합니다. 권한은 팀 역할, 리소스 소유권, 미디어 크레딧 또는 요금제 한도를 변경하지 않습니다.

매개변수

string
전송 계층에서는 선택 사항입니다. 생략하면 서버가 유효성 검사 전에 식별자를 추가합니다. 응답이 유실된 경우 안전하게 복구할 수 있도록 고정된 UUID v4를 직접 제공하세요.형식: “uuid”. 패턴: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$.
string
필수
텍스트 값입니다.최소 길이: 10. 최대 길이: 1200.
string
텍스트 값입니다.허용값: “square”, “landscape”, “portrait”. 기본값: “square”.
string
uploads/{yourUserId}/ 아래에 업로드된 JPG, PNG 또는 WebP 객체 키입니다. 원격 URL은 허용되지 않습니다.최소 길이: 1. 최대 길이: 512.
아래 JSON Schema는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다.

멱등성

각 변경 작업에 대해 requestId 또는 Idempotency-Key HTTP 헤더에 UUID v4를 사용하세요. 네트워크 오류 후에는 동일한 식별자와 동일한 인수를 재사용하세요. 둘 다 제공하는 경우 값이 일치해야 합니다. 저장된 요청을 재전송해도 작업이 반복되거나 월간 호출이 추가로 차감되지 않습니다. 실패하거나 중단된 요청은 자동으로 다시 시작되지 않습니다. 첫 실행이 일반적으로 동기식인 경우에도, 재시도 시 동일한 요청이 아직 실행 중이면 모든 변경 작업에서 HTTP 202를 반환할 수 있습니다. 실행은 완료되었지만 resultStored가 false이면, 재시도 시 원래 결과 대신 저장된 요청 상태를 HTTP 200으로 반환합니다. 해당 영역의 기록, 결과 또는 다운로드 액션으로 출력을 조회하세요.

요청 예제

예제의 리소스 식별자와 미디어 키를 계정에서 반환된 값으로 바꾸세요. 동일한 변경 작업을 재시도할 때는 요청 식별자를 유지하세요.

응답

이 작업은 실행 중에 HTTP 202를 반환합니다. requestId를 저장하고 해당 식별자와 원래 작업 이름으로 action_request_get을 폴링하세요. 폴링 상태는 running, completed, failed, interrupted입니다. 완료된 결과가 별도의 미디어 작업을 가리킬 수 있으므로 해당 작업의 상태 또는 출력 액션을 이어서 사용하세요. 이미지 생성 완료 후 핸들러가 반환하는 최종 생성 메타데이터입니다. 이미지 바이트, previewDataUrl 또는 다운로드 URL은 포함되지 않습니다.

결과 필드

이 요청 복구 및 폴링

연결이 끊어진 후에도 동일한 식별자를 사용하세요. resultStored가 false이면 해당 기록, 결과 또는 다운로드 액션을 통해 출력을 조회하세요. 진행 상황을 확인하기 위해 두 번째 생성을 시작하지 마세요.
HTTP 200

작업 참고 사항

  • images:write가 필요합니다. 프롬프트는 앞뒤 공백을 제거한 후 10~1200자여야 하며, 생성 전에도 정규화됩니다. aspectRatio의 기본값은 square이며 landscape 또는 portrait도 허용합니다. referenceImageKey는 최대 하나만 허용됩니다.
  • 장시간 실행되는 액션입니다. 최초 API/MCP 응답은 일반적으로 running을 나타냅니다. 여기에 표시된 최종 결과를 얻으려면 operation을 images_generate로 설정하고 동일한 requestId를 사용하여 action_request_get을 폴링하세요.
  • 계정의 일반 일일 이미지 생성 허용량을 사용합니다. 계정에서 생성한 이미지는 생성 후 7일이 지나면 만료됩니다. expiresAt 전에 결과를 다운로드하세요.
  • 인증 정보가 팀 컨텍스트로 연결되어 있어도 이 액션은 연결된 사용자 본인의 생성물과 업로드를 사용합니다.
  • 참조 키는 uploads/{yourUserId}/ 아래의 완료된 업로드를 가리켜야 하며 .jpg, .jpeg, .png 또는 .webp로 끝나야 합니다. 원격 URL, 다른 사용자의 키, 경로 탐색 세그먼트, 역슬래시, 퍼센트 이스케이프, 쿼리 문자열, 프래그먼트 및 제어 문자는 허용되지 않습니다.
  • 각 참조는 비어 있지 않아야 하며 최대 8 MiB(8,388,608바이트)여야 합니다. 확장자가 나타내는 이미지 유형으로 디코딩되어야 하며 가로와 세로가 각각 128–4096픽셀이어야 합니다. 디코딩된 픽셀 수에도 한도가 적용됩니다. 업로드된 참조는 재사용할 수 있으며, 이 생성 액션들은 업로드된 파일을 소모하거나 삭제하지 않습니다.
  • UUID v4 requestId 또는 HTTP Idempotency-Key 헤더를 사용하고 재시도 시 동일한 입력과 함께 재사용하세요. 통합 계층은 각 변경을 기록하고 다시 실행하지 않은 채 기록된 상태 또는 결과를 반환합니다. failed 또는 interrupted 상태의 요청은 자동으로 재시도되지 않습니다.
  • 이 사용자는 한 번에 이미지 하나만 생성할 수 있습니다. 생성 상태는 images_list와 images_get으로 확인하고, PNG 바이트는 images_download로 받으세요. 생성 식별자는 불투명 문자열입니다. requestId로 대체하지 마세요.

사용량

성공한 호출마다 월간 API/MCP 호출 1회가 차감됩니다. 미디어 크레딧과 해당 작업의 생성 허용량도 적용됩니다.

오류