Skip to main content

API 명세: 워크플로우 / 템플릿 기반 생성

기준일: 2026-03-04
대상 코드: backend-vivid-ai/src/workflows, backend-vivid-ai/src/generation

워크플로우 템플릿(그룹/변형) 관리와 템플릿 기반 생성 요청 API를 정리합니다.

Base Path​

/api/v1

1. 워크플로우 그룹 관리 (/workflows)​

1.1 GET /workflows​

  • 워크플로우 그룹 목록 조회
  • visibility 쿼리 지원: public(기본), private, all, archived

1.2 GET /workflows/:id​

  • 특정 워크플로우 그룹 상세 조회
  • 그룹에는 variants[]가 포함되며 sortOrder 기준 정렬됩니다.

1.3 POST /workflows​

  • 워크플로우 그룹 + variants 생성
  • variant별 inputConfig, workflowJson, requiredMappings, userInputs 저장

1.4 PATCH /workflows/:id​

  • 그룹/variants 수정 (variants는 전체 교체 방식)

1.5 DELETE /workflows/:id​

  • 아카이브 처리 (isArchived = true, isPublic = false)

1.6 POST /workflows/:id/restore​

  • 아카이브 해제

1.7 DELETE /workflows/:id/permanent​

  • 영구 삭제 (아카이브된 그룹만 허용)

2. 기능 키 매핑 (/workflows/mappings)​

Feature Key와 Workflow Group을 연결하는 추상화 레이어입니다.

2.1 GET /workflows/mappings​

  • 매핑 전체 조회
  • 일반 유저: PUBLIC만 조회
  • 관리자: PUBLIC, ADMIN_ONLY, PRIVATE 조회

2.2 GET /workflows/mappings/:featureKey​

  • 특정 featureKey 매핑 조회

2.3 POST /workflows/mappings (Admin)​

  • 매핑 생성/수정(upsert)
  • featureKey, workflowGroupId, visibility 등 설정

2.4 DELETE /workflows/mappings/:featureKey (Admin)​

  • 매핑 삭제

3. 템플릿 기반 생성 요청 (/generation)​

3.1 POST /generation/from-template​

워크플로우 템플릿 기반 생성 API입니다.

Request Body​

{
  "featureKey": "PERSONA_TO_IMAGE_GEN",
  "modifications": {
    "persona_id": "7d8f9d52-....",
    "text_1": "cinematic portrait, soft rim light",
    "text_2": "",
    "image_2": "s3://.../ref-a.png",
    "aspect_ratio": "1:1",
    "quality": "FHD"
  }
}

입력 규칙​

  • workflowId 또는 featureKey 중 최소 1개 필수
  • 둘 다 전달한 경우, featureKey 매핑 결과와 workflowId가 일치해야 함
  • modifications는 동적 입력 값 맵
  • quality는 SD, HD, FHD 중 하나를 사용
  • text_2를 사용하지 않는 경우에도 "" 전달을 권장

서버 처리 핵심​

  1. 매핑 해석: featureKey가 있으면 매핑된 workflowGroupId 결정
  2. 공개성 검증:
    • 아카이브된 워크플로우 사용 불가
    • 비공개 워크플로우는 관리자만 사용 가능
  3. 페르소나 컨텍스트 검증:
    • persona_id 전달 시 소유권 검증
    • 검증 통과 시 image_1을 페르소나의 신뢰 가능한 S3 경로로 강제 대체
  4. Variant 선택:
    • text/image/video/audio 입력 개수 기준 exact-match
    • 미매칭 시 400 에러
  5. 사용자 입력 주입:
    • requiredMappings + userInputs 기준 주입
    • targetNodeField는 dot 키(resize_type.width)를 flat/nested 모두 처리
  6. 비용 계산:
    • quality + batch_size 기준 VT 차감
  7. 큐 적재:
    • creationId 생성 후 SQS에 작업 등록

Response (202 Accepted)​

{
  "creationId": "db0dd7e5-2d0b-4802-bf47-a60707387396"
}

3.2 POST /generation​

워크플로우 JSON 직접 실행 API입니다.
운영 기능보다는 관리/실험성 요청(예: admin/generate) 용도로 사용합니다.

Request Body​

{
  "workflow": {
    "3": { "...": "..." }
  }
}

Response (202 Accepted)​

{
  "creationId": "f0d0e6aa-...."
}

4. 데이터 스키마 (요약)​

4.1 WorkflowGroup​

interface WorkflowGroup {
  id: string;
  name: string;
  description?: string;
  type: 'IMAGE' | 'VIDEO' | 'AUDIO' | 'TEXT';
  isPublic: boolean;
  isDefault: boolean;
  isPreload: boolean;
  isArchived: boolean;
  priceSD: number;
  priceHD: number;
  priceFHD: number;
  variants: WorkflowVariant[];
  createdAt: string;
  updatedAt: string;
}

4.2 WorkflowVariant​

interface WorkflowVariant {
  id: string;
  inputConfig: { text?: number; image?: number; video?: number; audio?: number };
  workflowJson: object;
  requiredMappings: Record<string, { nodeId: string; field: string }>;
  userInputs?: UserInputSchema[];
  sortOrder: number; // exact-match 다중 후보 우선순위
}

4.3 WorkflowMapping​

interface WorkflowMapping {
  featureKey: string;
  displayName: string;
  category: string;
  visibility: 'PUBLIC' | 'ADMIN_ONLY' | 'PRIVATE';
  workflowGroupId: string;
  description?: string;
  updatedAt: string;
}

4.4 UserInputSchema​

interface UserInputSchema {
  id: string;
  label: string;
  type: 'text' | 'number' | 'image_upload' | 'video_upload' | 'audio_upload' | 'checkbox' | 'select';
  targetNodeId: string;
  targetNodeField: string;
  defaultValue?: string | number | boolean;
  min?: number;
  max?: number;
  options?: Array<{ label: string; value: string | number }>;
}

5. 운영 메모​

  1. Persona/Scene 계열 기능은 workflowId 직접 전달보다 featureKey 전달을 우선 사용합니다.
  2. featureKey 기반 생성은 관리자가 비공개 전환한 워크플로우를 일반 유저가 우회 호출하지 못하도록 방어합니다.
  3. 재현성 저장 정책:
    • creations.snapshot(jsonb)을 원본으로 저장:
      • 최소 키: text_1, text_2, personaId, lookId, featureKey, workflowGroupId, variantId
      • 선택 키: quality(SD/HD/FHD), ratio, refs, seed, batchSize, recipePrompts
    • creations projection 컬럼 저장:
      • resolved_prompt, resolved_negative_prompt, ratio, refs
    • creation_results 필수 컬럼 저장:
      • seed, resultIndex, s3Path, thumbnailS3Path
  4. 배치/정렬 정책:
    • 관계: Creation(1) : CreationResult(N) (Persona 계열 기본 N=4)
    • 히스토리/API 정렬: creation.createdAt DESC, 동일 creationId 내 resultIndex ASC