문서 · API 참조

API 참조

엔드포인트, 키, 제한. AI 이미지 엔드포인트(생성, 제거, 확장)의 인증, CORS, 및 레이트 제한에 대한 참조입니다.

Morph는 api.morph.cool에서 AI 기반 이미지 엔드포인트를 제공합니다. 이 엔드포인트는 Artboard의 AI 기능을 지원하며, 개발자가 통합을 구축할 때 사용할 수 있습니다.

기본 URL: https://api.morph.cool
모든 요청은 HTTPS를 사용합니다. HTTP 요청은 거부됩니다.

인증

AI 이미지 엔드포인트(생성, 제거, 확장)는 기본 사용에 인증이 필요하지 않습니다. IP 주소별로 속도 제한이 적용됩니다. 사용자 데이터를 수정하는 엔드포인트(변환, 벨, 리더보드)는 Bearer 토큰으로 Authorization 헤더에 JWT 토큰을 전달해야 합니다.

Authorization: Bearer <jwt_token>

Rate Limits

모든 엔드포인트는 오용을 방지하기 위해 요청 제한이 적용됩니다. 제한을 초과하면 429 상태 코드와 JSON 오류가 반환됩니다.

Artboard AI 엔드포인트 — IP당 분당 10회 요청 (KV 기반).
변환 로깅 — 인증이 필요하며 별도의 IP 제한이 없습니다.
오류 보고 — IP당 분당 30회 요청.
대기열 — IP당 분당 10회 요청.

이미지 생성

POST /artboard/generate

텍스트 기반 이미지 생성 및 인페인팅. 텍스트 프롬프트를 기반으로 선택된 영역을 채우기 위해 마스크가 적용된 캔버스 이미지를 전송합니다. 또한 이미지의 텍스트 설명을 반환하는 '설명 모드'도 지원합니다.

필드	타입	설명
프롬프트	string	생성할 내용의 텍스트 설명입니다. 설명 모드에서는 필요하지 않습니다.
canvasImage필수	string	캔버스 콘텐츠의 Base64 인코딩된 PNG입니다.
maskImage	string	선택 영역 마스크의 Base64 인코딩된 PNG. 흰색 = 채워야 할 영역. inpainting에 필수적이며, describe에는 필요하지 않습니다.
모드	string	이미지 설명 모드로 `"describe"`로 설정하세요. 생성을 위해 생략하세요.

생성 응답:

{
  "result": "<base64_png_string>"
}

응답 설명:

{
  "result": "A detailed text description of the image content."
}

검증: 설명 모드에서 PNG는 최소 64×64 픽셀이어야 합니다. 더 작은 이미지는 REGION_TOO_SMALL 오류를 반환합니다.

객체 제거

POST /artboard/remove

AI 기반 개체 제거. 마스크에서 개체를 그려 덮고 모델이 맥락에 맞는 내용으로 영역을 채웁니다.

필드	타입	설명
canvasImage필수	string	캔버스의 Base64 인코딩된 PNG입니다.
maskImage필수	string	Base64 인코딩된 PNG 마스크. 흰색 = 제거할 영역.

응답:

{
  "result": "<base64_png_string>"
}

생성 확장

POST /artboard/expand

주어진 방향으로 캔버스를 확장합니다. AI가 기존 이미지와 일치하는 내용으로 새 영역을 채웁니다. 경계 픽셀 확장을 사용하여 맥락을 유지합니다.

필드	타입	설명
canvasImage필수	string	캔버스의 Base64 인코딩된 PNG입니다. 가로세로 64~4096px여야 합니다.
방향필수	string	한 가지: `left`, `right`, `top`, `bottom`, `all`.
expandPx필수	number	Pixels to expand. Range: 64–512.
프롬프트	string	생성된 콘텐츠를 안내하는 선택적 텍스트 프롬프트입니다.

응답:

{
  "result": "<base64_png_string>"
}

검증: 소스 이미지는 각 변이 64~4096픽셀이어야 합니다. 확장된 캔버스는 어느 방향으로도 4096픽셀을 초과할 수 없습니다. 위반 시 REGION_TOO_SMALL 또는 CANVAS_TOO_LARGE 오류가 반환됩니다.

오류 응답

모든 엔드포인트는 error 필드를 포함한 JSON 오류 응답을 반환합니다:

{
  "error": "RATE_LIMITED"
}

흔한 오류 코드:

RATE_LIMITED — 요청이 너무 많습니다. 잠시 기다렸다가 다시 시도하세요.
REGION_TOO_SMALL — 이미지 크기가 최소 64×64픽셀 미만입니다.
CANVAS_TOO_LARGE — 확장된 캔버스가 4096px 한계를 초과했습니다.
MISSING_FIELDS — 필수 필드가 제공되지 않았습니다.

참고

AI 모델 — 모든 인페인팅 엔드포인트는 Cloudflare Workers AI를 통해 Stable Diffusion v1.5를 사용합니다. 추론 단계는 20회로 제한됩니다.
이미지 형식 — 모든 이미지는 base64 인코딩된 PNG여야 합니다.
프라이버시 — 이미지는 메모리에서 처리되며 저장, 기록, 또는 모델 훈련에 사용되지 않습니다.
CORS — 엔드포인트는 morph.cool, www.morph.cool, localhost:5173에서 요청을 허용합니다.
타임아웃 — 클라이언트는 30초 타임아웃을 설정해야 합니다. 서버 측 처리는 거의 15초를 초과하지 않습니다.

Morph 열기