모범 사례

읽기 전용 시작, 견적 후 생성, 같은 멱등 키 재시도 등 여덟 가지입니다.

읽기 전용으로 시작하기

새 에이전트는 조회 기능만 허용한 키로 시작합니다. 동작을 확인한 뒤에 필요한 기능을 하나씩 추가합니다.

견적 후 생성하기

견적과 접수는 같은 계산입니다. 견적을 사용자나 자기 정책에 비춰 확인하고 접수하세요. 공개 REST는 maxCherry로 이 확인을 요청에 묶습니다.
curl -sS -X POST "$MELLOWZ_STUDIO_URL/v1/images" \
  -H "Authorization: Bearer $MELLOWZ_STUDIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modelId":"<모델 id>","prompt":"숲속의 작은 집","maxCherry":100,"idempotencyKey":"best-practice-0001"}'

키 권한 좁히기

  • 기능은 필요한 것만 허용합니다.
  • 만료는 짧게, 지출 한도는 쓸 만큼만 둡니다.
  • 에이전트마다 키를 따로 둡니다. 하나를 폐기해도 나머지가 영향받지 않습니다.

제안은 승인될 때까지 적용된 것이 아님

작품 수정 제안을 올린 뒤에는 "승인 대기 중"이라고 사용자에게 말합니다. 승인 전에는 작품이 바뀌지 않으므로 적용됐다고 가정하고 다음 단계를 이어 가지 않습니다. 제안 전에는 시뮬레이션이 있는 서버에서 먼저 결과를 확인합니다. 스킬별 규칙은 에이전트 스킬에 있습니다.

재시도에는 같은 멱등 키

네트워크 오류로 응답을 못 받았을 때는 같은 idempotencyKey와 같은 본문으로 다시 보냅니다. 새 키로 보내면 같은 작업이 두 번 접수될 수 있습니다. 상세는 안전한 자동화에 있습니다.

호출 한도 고려하기

기능마다 시간당 한도가 있습니다. 진행 조회는 응답이 알려 주는 대기 시간을 지키고, 429가 오면 Retry-After만큼 기다립니다. 끝날 때까지 기다리는 일은 웹훅으로 줄입니다.

결과는 에셋에서 이어 쓰기

생성 결과는 에셋으로 보관됩니다. 같은 결과를 다음 작업의 참조로 쓰려면 에셋 참조(assetId, revision)로 넘기고, 링크를 저장해 두지 않습니다. 링크는 만료됩니다.

정기 실행이 필요할 때

예약 실행 기능은 없습니다. 자기 쪽 스케줄러에서 호출하되, 매번 견적 상한(maxCherry)과 키의 지출 한도를 걸어 두세요.

관련