레시피

cURL·JavaScript·Python 예시입니다.
레시피의 코드는 서버 주소와 키를 환경변수로 받습니다. 값은 직접 쓰지 않습니다.
환경 준비 — bash
export MELLOWZ_STUDIO_URL="<서버 주소>"
export MELLOWZ_STUDIO_TOKEN="<연결 화면에서 만든 키>"

키가 통하는지 확인하기

모델 목록 조회가 통하면 키와 권한이 맞는 것입니다. 401이면 키나 권한 문제입니다.
curl -sS "$MELLOWZ_STUDIO_URL/v1/models/image" \
  -H "Authorization: Bearer $MELLOWZ_STUDIO_TOKEN"

모델과 옵션 보기

위 응답에서 모델 하나를 고릅니다. 모델마다 지원하는 비율, 해상도, 품질 값이 다르므로, 접수에는 그 모델이 지원하는 값만 씁니다. 영상과 오디오는 /v1/models/video, /v1/models/audio입니다.

이미지 만들기

maxCherry는 감수할 상한입니다. <모델 id>와 상한은 위에서 본 가격에 맞춰 정합니다. 키는 요청마다 새로 만듭니다.
curl -sS -X POST "$MELLOWZ_STUDIO_URL/v1/images" \
  -H "Authorization: Bearer $MELLOWZ_STUDIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "<모델 id>",
    "prompt": "비 오는 골목의 고양이",
    "candidateCount": 1,
    "maxCherry": 100,
    "idempotencyKey": "recipe-image-0001"
  }'

영상 만들기

영상은 캔버스 문서의 revision을 지정합니다. 문서는 앱에서 만들거나 MCP로 저작한 것입니다.
curl -sS -X POST "$MELLOWZ_STUDIO_URL/v1/videos" \
  -H "Authorization: Bearer $MELLOWZ_STUDIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "<문서 id>",
    "revision": 1,
    "tier": "draft",
    "maxCherry": 500,
    "idempotencyKey": "recipe-video-0001"
  }'

음악 만들기

curl -sS -X POST "$MELLOWZ_STUDIO_URL/v1/audio" \
  -H "Authorization: Bearer $MELLOWZ_STUDIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "<모델 id>",
    "prompt": "잔잔한 피아노 배경음",
    "maxCherry": 100,
    "idempotencyKey": "recipe-audio-0001"
  }'

작업 폴링하고 결과 받기

접수 응답의 작업 id로 조회합니다. 이미지 접수 응답은 작업 객체이고 id가 작업 id입니다. 영상과 오디오는 jobs 배열의 각 항목 id입니다. 진행 중이면 poll_after_seconds(이미지는 응답 최상위, 오디오는 job 안)만큼 기다렸다가 다시 부르고, 끝나면 멈춥니다. 영상 응답에는 이 값이 없으니 10초 간격으로 부릅니다.
curl -sS "$MELLOWZ_STUDIO_URL/v1/images/<작업 id>" \
  -H "Authorization: Bearer $MELLOWZ_STUDIO_TOKEN"
끝났다고 성공은 아닙니다. 이미지는 done이 성공이고 failed일 때 job.error를, 영상과 오디오는 succeeded가 성공이고 failed일 때 job.failure를 확인하세요. 폴링 대신 웹훅으로 종료 알림을 받을 수도 있습니다.

업로드한 파일 쓰기

이미지 접수의 referenceAssets는 에셋 참조(assetId, revision) 배열이며 최대 5개입니다. 파일은 먼저 에셋으로 올려야 합니다. 업로드는 POST /assets이고 키에 에셋 업로드 권한이 있어야 합니다. 멀티파트 폼으로 보내며 파일은 20MiB까지입니다.
폼 필드필수뜻
file예파일 하나
name아니요에셋 이름
folderId아니요넣을 폴더
role아니요character, background, prop 중 하나
tags아니요문자열 배열을 JSON 글자로
위 필드 말고 다른 필드를 보내면 400입니다. 성공하면 201과 함께 에셋 정보가 오고, 그 assetId와 revision을 referenceAssets에 넣습니다.
curl -sS -X POST "$MELLOWZ_STUDIO_URL/assets" \
  -H "Authorization: Bearer $MELLOWZ_STUDIO_TOKEN" \
  -F "file=@./reference.png" \
  -F "name=참조 이미지"

작업 취소하기

대기 중인 작업만 취소됩니다. 이미지는 취소에도 멱등 키가 필요합니다.
curl -sS -X POST "$MELLOWZ_STUDIO_URL/v1/images/<작업 id>/cancel" \
  -H "Authorization: Bearer $MELLOWZ_STUDIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "idempotencyKey": "recipe-cancel-0001" }'
이미 시작된 작업은 409(cancel_reason: already_started)입니다. 영상 탭의 경로를 /v1/audio/<작업 id>/cancel로 바꾸면 오디오 취소입니다.

사용량 읽기

사용량을 읽는 공개 경로는 없습니다. 설정의 개발자 사용량 화면(/settings/developer-usage)에서 일, 키, 모델별로 봅니다. 환불분은 합계에서 빠집니다.

관련