VisualPort API

작업 생성 / Create a Job

외부 서비스의 서버에서 호출합니다. API 키를 브라우저 코드에 넣지 마세요. / Call from your server. Never expose keys in browser code.

const base = "https://visualport.song-family-5042.chatgpt.site";
const headers = {
  Authorization: "Bearer " + process.env.VISUALPORT_API_KEY,
  "Content-Type": "application/json",
  "Idempotency-Key": crypto.randomUUID()
};
const response = await fetch(base + "/api/v1/jobs", {
  method: "POST", headers,
  body: JSON.stringify({
    kind: "image",
    prompt: "A white porcelain vase on a green studio background",
    aspectRatio: "16:9"
  })
});
if (!response.ok) throw new Error(await response.text());
const job = await response.json();
// Poll GET /api/v1/jobs/{job.id} every 6+ seconds.
// Download job.downloadUrl with the same Bearer authorization.

지원 작업 / Operations

image: Higgsfield Soul · prompt (5–3,000자), aspectRatio, 선택적 image. / Optional reference image.
cutout: image 필수 · subject: portrait 또는 object. 투명 PNG, 원본 유지. / Required image, transparent PNG, original subject preserved.
thumbnail: image와 title 필수 · template: full-photo, editorial, product · subtitle 선택 · locale: ko, en, ja, zh, es, pt, hi · 1280×720 PNG. 브라우저의 1,000개 멀티레이어 시안과는 별도의 API 전용 3종입니다.

입력·사용량 / Inputs and Limits

image는 data:image/png;base64,... 형식이며 PNG·JPEG·WebP, 최대 5MB입니다. 누끼·썸네일은 최대 1,600만 화소이며 처리시간은 최대 10분입니다. 외부 이미지 URL과 SVG는 받지 않습니다. / Base64 data URLs only; no remote URL fetching or SVG.

월 결제와 별개로 사용량은 최근 30일을 기준으로 계산합니다. 이미지 100회, 누끼·썸네일 합산 1,000회이며 사이트 안에서 생성한 이미지도 같은 한도에서 차감합니다. 실패·취소·안전 차단은 차감하지 않고, 접수 불명 작업은 확인 전까지 예약합니다. 초과 결제·이월은 없습니다.

조회·다운로드 / Status and Download

GET /api/v1/jobs 및 GET /api/v1/jobs/작업ID로 조회합니다. 완료 후 resultUrl 또는 downloadUrl에 같은 Authorization 헤더를 넣어 요청하세요. 반환 URL은 이 사이트 기준 상대 경로입니다. / Poll at least 6 seconds apart and download with the same Bearer key.

결과는 생성 요청 시점부터 30일간 다운로드할 수 있습니다. 처리 서버의 임시 입력과 출력은 최대 24시간 보관합니다. 만료 파일은 삭제 대상이 되며 요청 기록은 사용량과 중복 실행 방지를 위해 보관합니다.

중복·오류 / Retries and Errors

Idempotency-Key에는 UUID를 사용하세요. 통신 오류 후에는 같은 키와 같은 내용을 다시 보내거나 기존 작업을 조회합니다. 다른 키로 재전송하면 새 작업입니다. unknown 상태에서는 재생성하지 말고 sales@ppv.kr로 작업 ID를 알려주세요.

400 잘못된 입력 · 401 인증 · 403 권한 · 404 소유하지 않은/만료된 결과 · 409 요청 충돌 · 413 크기 초과 · 429 사용량/요청 한도 · 503 연결 준비 또는 제공자 오류. / Errors include a JSON error message.

기존 Pro에서 API 요금제로 변경할 때에는 중복 결제를 막기 위해 고객지원 확인이 필요합니다. / Contact support to change an existing plan.