# AUTO-GENERATED by scripts/generate-openapi.mjs. Do not edit manually.
openapi: 3.1.0
info:
  title: EcomGen API
  version: 0.1.0
  description: Backend-first contract for the EcomGen desktop-first local application.
security: []
servers:
  - url: http://localhost:8787/api/v1
paths:
  /health:
    get:
      operationId: getHealth
      responses:
        "200":
          description: Service is healthy.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
  /ecom-templates:
    get:
      operationId: listEcomDetailsImageTemplates
      responses:
        "200":
          description: Structured templates adapted from the pinned ecom-details-image upstream Skill.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EcomTemplatesResponse"
  /user-templates:
    get:
      operationId: listUserTemplates
      responses:
        "200":
          description: User-defined custom prompt templates.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserTemplateList"
    post:
      operationId: createUserTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserTemplateInput"
      responses:
        "201":
          description: Custom template created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserTemplateItem"
        "400":
          $ref: "#/components/responses/ValidationError"
  /user-templates/{templateId}:
    parameters:
      - $ref: "#/components/parameters/UserTemplateId"
    patch:
      operationId: updateUserTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserTemplateInput"
      responses:
        "200":
          description: Custom template updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserTemplateItem"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteUserTemplate
      responses:
        "204":
          description: Custom template deleted.
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /suites:
    get:
      operationId: listSuites
      parameters:
        - name: q
          in: query
          required: false
          description: Case-insensitive substring match over name, category l1/l2/leaf and description.
          schema:
            type: string
        - name: l1
          in: query
          required: false
          description: Exact category L1 filter.
          schema:
            type: string
        - name: l2
          in: query
          required: false
          description: Exact category L2 filter, applied on top of l1.
          schema:
            type: string
        - name: ids
          in: query
          required: false
          description: Comma-separated suite IDs; when present the response returns exactly those suites and ignores q/l1/l2/cursor/limit.
          schema:
            type: string
        - $ref: "#/components/parameters/Cursor"
        - name: limit
          in: query
          required: false
          description: Page size, clamped to 1..100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: Available e-commerce image suites (built-in, drop-in directory, and user-imported).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EcomSuitesResponse"
    post:
      operationId: createUserSuite
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EcomSuiteFile"
      responses:
        "201":
          description: User suite imported.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EcomSuiteDetail"
        "400":
          $ref: "#/components/responses/ValidationError"
        "409":
          $ref: "#/components/responses/Conflict"
  /suites/refresh:
    post:
      operationId: refreshSuites
      responses:
        "200":
          description: Suite catalog reloaded from the drop-in directory and database.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EcomSuitesResponse"
  /suites/{suiteId}:
    parameters:
      - $ref: "#/components/parameters/SuiteId"
    get:
      operationId: getSuite
      responses:
        "200":
          description: Suite detail with every storyboard shot.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EcomSuiteDetail"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      operationId: updateUserSuite
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EcomSuiteFile"
      responses:
        "200":
          description: User suite updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EcomSuiteDetail"
        "400":
          $ref: "#/components/responses/ValidationError"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteUserSuite
      responses:
        "204":
          description: User suite deleted.
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /suite-categories:
    get:
      operationId: listSuiteCategories
      responses:
        "200":
          description: Built-in suite category taxonomy (L1 and L2) for browsing and search.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EcomSuiteCategoriesResponse"
  /suite-forge-jobs:
    get:
      operationId: listSuiteForgeJobResults
      parameters:
        - name: limit
          in: query
          required: false
          description: Maximum number of recent forge jobs to return, clamped to 1..50.
          schema:
            type: integer
            minimum: 1
            maximum: 50
      responses:
        "200":
          description: Recent suite forge jobs, including running and failed ones, each with its draft summary when the run produced one.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuiteForgeJobList"
    post:
      operationId: createSuiteForgeJob
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/CreateSuiteForgeJobInput"
      responses:
        "202":
          description: Suite forge job accepted (or an existing job reused for an identical request).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "400":
          $ref: "#/components/responses/ValidationError"
        "422":
          $ref: "#/components/responses/CapabilityUnsupported"
  /suite-forge-jobs/{jobId}/result:
    parameters:
      - $ref: "#/components/parameters/JobId"
    get:
      operationId: getSuiteForgeResult
      responses:
        "200":
          description: Draft or committed forged suite for the job.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuiteForgeResult"
        "404":
          $ref: "#/components/responses/NotFound"
  /suite-forge-jobs/{jobId}/commit:
    parameters:
      - $ref: "#/components/parameters/JobId"
    post:
      operationId: commitSuiteForgeResult
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EcomSuiteFile"
      responses:
        "200":
          description: Forged suite imported into the user suite catalog.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuiteForgeResult"
        "400":
          $ref: "#/components/responses/ValidationError"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /providers:
    get:
      operationId: listProviders
      responses:
        "200":
          description: Provider configurations.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderList"
    post:
      operationId: createProvider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProviderInput"
      responses:
        "201":
          description: Provider created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderConfig"
        "400":
          $ref: "#/components/responses/ValidationError"
  /providers/{providerId}:
    parameters:
      - $ref: "#/components/parameters/ProviderId"
    patch:
      operationId: updateProvider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProviderInput"
      responses:
        "200":
          description: Provider updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderConfig"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteProvider
      responses:
        "204":
          description: Provider deleted.
        "409":
          $ref: "#/components/responses/Conflict"
  /providers/{providerId}/test:
    parameters:
      - $ref: "#/components/parameters/ProviderId"
    post:
      operationId: testProviderConnection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TestProviderInput"
      responses:
        "200":
          description: Provider connectivity result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestProviderConnectionResult"
        "502":
          $ref: "#/components/responses/ProviderError"
  /search-sources:
    get:
      operationId: listSearchSources
      responses:
        "200":
          description: Search source configurations in execution priority order.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSourceList"
    post:
      operationId: createSearchSource
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSearchSourceInput"
      responses:
        "201":
          description: Search source created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSourceConfig"
        "400":
          $ref: "#/components/responses/ValidationError"
  /search-sources/{sourceId}:
    parameters:
      - name: sourceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    patch:
      operationId: updateSearchSource
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSearchSourceInput"
      responses:
        "200":
          description: Search source updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchSourceConfig"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteSearchSource
      responses:
        "204":
          description: Search source deleted.
        "404":
          $ref: "#/components/responses/NotFound"
  /projects:
    get:
      operationId: listProjects
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - name: archived
          in: query
          required: false
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Projects.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectList"
    post:
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProjectInput"
      responses:
        "201":
          description: Project created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
  /projects/{projectId}:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    get:
      operationId: getProject
      responses:
        "200":
          description: Project.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDetail"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      operationId: updateProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProjectInput"
      responses:
        "200":
          description: Project updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
    delete:
      operationId: deleteProject
      responses:
        "204":
          description: Project deleted.
        "409":
          $ref: "#/components/responses/Conflict"
  /projects/{projectId}/assets:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    get:
      operationId: listAssets
      responses:
        "200":
          description: Assets.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AssetList"
    post:
      operationId: uploadAsset
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/UploadAssetInput"
      responses:
        "200":
          description: Asset uploaded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Asset"
  /assets/{assetId}:
    parameters:
      - $ref: "#/components/parameters/AssetId"
    patch:
      operationId: updateAsset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAssetInput"
      responses:
        "200":
          description: Asset updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Asset"
    delete:
      operationId: deleteAsset
      responses:
        "204":
          description: Asset deleted.
        "404":
          $ref: "#/components/responses/NotFound"
  /library-assets:
    get:
      operationId: listLibraryAssets
      parameters:
        - name: kind
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/LibraryItemKind"
        - name: q
          in: query
          required: false
          schema:
            type: string
        - $ref: "#/components/parameters/Cursor"
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: Global asset library view over uploads and generated results, deduplicated by content hash.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LibraryAssetList"
  /projects/{projectId}/assets/from-library:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    post:
      operationId: copyLibraryAssetToProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CopyLibraryAssetToProjectInput"
      responses:
        "201":
          description: Asset copied from the library into the project.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Asset"
        "404":
          $ref: "#/components/responses/NotFound"
  /projects/{projectId}/planning-jobs:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    post:
      operationId: createPlanningJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePlanningJobInput"
      responses:
        "202":
          description: Planning job queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "422":
          $ref: "#/components/responses/CapabilityUnsupported"
  /projects/{projectId}/planning-config-snapshots:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    get:
      operationId: listPlanningConfigSnapshots
      responses:
        "200":
          description: Recent planning configuration snapshots.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlanningConfigSnapshotList"
  /projects/{projectId}/planning-config-snapshots/{snapshotId}/apply:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
      - name: snapshotId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: applyPlanningConfigSnapshot
      responses:
        "200":
          description: Applied planning configuration snapshot.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApplyPlanningConfigSnapshotResult"
        "409":
          $ref: "#/components/responses/Conflict"
  /projects/{projectId}/copywriting-jobs:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    post:
      operationId: createCopywritingJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCopywritingJobInput"
      responses:
        "200":
          description: Existing copywriting job reused.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "202":
          description: Copywriting job queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "400":
          $ref: "#/components/responses/ValidationError"
        "422":
          $ref: "#/components/responses/CapabilityUnsupported"
  /copywriting-jobs/{jobId}/result:
    parameters:
      - $ref: "#/components/parameters/JobId"
    get:
      operationId: getCopywritingResult
      responses:
        "200":
          description: Generated copywriting result.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CopywritingResult"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
  /projects/{projectId}/storyboard:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    get:
      operationId: getStoryboard
      responses:
        "200":
          description: Current storyboard.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StoryboardBundle"
  /projects/{projectId}/storyboard/confirm:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    post:
      operationId: confirmStoryboard
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfirmStoryboardInput"
      responses:
        "200":
          description: Storyboard frozen for generation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Storyboard"
        "409":
          $ref: "#/components/responses/Conflict"
  /storyboard-items/{itemId}:
    parameters:
      - $ref: "#/components/parameters/StoryboardItemId"
    patch:
      operationId: updateStoryboardItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateStoryboardItemInput"
      responses:
        "200":
          description: Storyboard item updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StoryboardItem"
        "409":
          $ref: "#/components/responses/Conflict"
    delete:
      operationId: deleteStoryboardItem
      responses:
        "204":
          description: Draft storyboard item deleted.
        "409":
          $ref: "#/components/responses/Conflict"
  /projects/{projectId}/generation-jobs:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    post:
      operationId: createGenerationJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateGenerationJobInput"
      responses:
        "202":
          description: Generation job queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GenerationJobsResponse"
        "409":
          $ref: "#/components/responses/Conflict"
  /projects/{projectId}/outputs/{outputId}/edit-sessions:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
      - $ref: "#/components/parameters/OutputId"
    post:
      operationId: createEditSession
      responses:
        "201":
          description: Edit session created or reused.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EditSession"
  /edit-sessions/{sessionId}:
    parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getEditSession
      responses:
        "200":
          description: Edit session and turns.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/EditSession"
                  - type: object
                    required:
                      - turns
                    properties:
                      turns:
                        type: array
                        items:
                          $ref: "#/components/schemas/EditTurn"
                      versions:
                        type: array
                        items:
                          $ref: "#/components/schemas/Output"
  /edit-sessions/{sessionId}/memory:
    parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    patch:
      operationId: updateEditSessionMemory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateEditSessionMemoryInput"
      responses:
        "200":
          description: Updated edit session memory.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EditSession"
        "404":
          $ref: "#/components/responses/NotFound"
  /edit-sessions/{sessionId}/reference-assets:
    parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: listEditReferenceAssets
      responses:
        "200":
          description: Project and temporary reference assets available to this edit session.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EditReferenceAssetList"
    post:
      operationId: uploadEditReferenceAsset
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/UploadEditReferenceAssetInput"
      responses:
        "201":
          description: Temporary reference asset uploaded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EditReferenceAsset"
  /edit-sessions/{sessionId}/reference-assets/{referenceAssetId}:
    parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: referenceAssetId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    delete:
      operationId: deleteEditReferenceAsset
      responses:
        "204":
          description: Temporary reference asset deleted.
  /edit-sessions/{sessionId}/reference-assets/{referenceAssetId}/promote:
    parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: referenceAssetId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: promoteEditReferenceAsset
      responses:
        "201":
          description: Temporary reference asset saved to the project.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EditReferenceAsset"
  /edit-sessions/{sessionId}/turns:
    parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: createEditTurn
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/CreateEditTurnInput"
      responses:
        "202":
          description: Edit plan queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EditTurnQueuedResponse"
  /edit-sessions/{sessionId}/select-output:
    parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: selectEditSessionOutput
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SelectEditSessionOutputInput"
      responses:
        "200":
          description: Current edit output changed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EditSession"
  /edit-turns/{turnId}:
    parameters:
      - name: turnId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getEditTurn
      responses:
        "200":
          description: Edit turn state and plan.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EditTurn"
  /edit-turns/{turnId}/approve:
    parameters:
      - name: turnId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: approveEditTurn
      responses:
        "202":
          description: Edit generation queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApproveEditTurnResponse"
  /jobs/{jobId}:
    parameters:
      - $ref: "#/components/parameters/JobId"
    get:
      operationId: getJob
      responses:
        "200":
          description: Job state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
  /jobs/{jobId}/cancel:
    parameters:
      - $ref: "#/components/parameters/JobId"
    post:
      operationId: cancelJob
      responses:
        "202":
          description: Cancellation requested.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
  /jobs/{jobId}/retry:
    parameters:
      - $ref: "#/components/parameters/JobId"
    post:
      operationId: retryJob
      description: Supersedes the original failed job as CANCELLED and queues a replacement job. Repeated retries on the same job respond with 409.
      responses:
        "202":
          description: New retry job queued; the original job is now CANCELLED.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
  /outputs/{outputId}/layer-plan:
    parameters:
      - $ref: "#/components/parameters/OutputId"
    get:
      operationId: getLayerPlan
      responses:
        "200":
          description: Layer plan state and recognized elements.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LayerPlan"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      operationId: createLayerPlan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateLayerPlanInput"
      responses:
        "200":
          description: Existing plan reused for the same output content.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LayerPlan"
        "202":
          description: Layer recognition job queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LayerPlan"
        "404":
          $ref: "#/components/responses/NotFound"
  /outputs/{outputId}/layer-exports:
    parameters:
      - $ref: "#/components/parameters/OutputId"
    get:
      operationId: getLayerExport
      responses:
        "200":
          description: Latest layer export state for the output.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LayerExport"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      operationId: createLayerExport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateLayerExportInput"
      responses:
        "202":
          description: Layer export job queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LayerExportBundle"
        "404":
          $ref: "#/components/responses/NotFound"
  /outputs/{outputId}/layer-exports/history:
    parameters:
      - $ref: "#/components/parameters/OutputId"
    get:
      operationId: listLayerExports
      responses:
        "200":
          description: All layer exports of the output, newest first.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LayerExportHistory"
        "404":
          $ref: "#/components/responses/NotFound"
  /projects/{projectId}/export-jobs:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    post:
      operationId: createExportJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateExportJobInput"
      responses:
        "202":
          description: Export job queued.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportJobBundle"
  /exports/{exportId}:
    parameters:
      - $ref: "#/components/parameters/ExportId"
    get:
      operationId: getExport
      responses:
        "200":
          description: Export package state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Export"
  /files/thumbnails/{hash}:
    parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: downloadThumbnail
      responses:
        "200":
          description: Lazily generated webp thumbnail for a library asset, keyed by content hash.
        "404":
          $ref: "#/components/responses/NotFound"
  /files/assets/{assetId}:
    parameters:
      - $ref: "#/components/parameters/AssetId"
    get:
      operationId: downloadAsset
      responses:
        "200":
          description: Original asset bytes.
        "404":
          $ref: "#/components/responses/NotFound"
  /files/outputs/{outputId}:
    parameters:
      - $ref: "#/components/parameters/OutputId"
    get:
      operationId: downloadOutput
      responses:
        "200":
          description: Generated image bytes.
        "404":
          $ref: "#/components/responses/NotFound"
  /files/exports/{exportId}:
    parameters:
      - $ref: "#/components/parameters/ExportId"
    get:
      operationId: downloadExport
      responses:
        "200":
          description: ZIP package bytes.
        "404":
          $ref: "#/components/responses/NotFound"
  /files/layer-exports/{layerExportId}:
    parameters:
      - $ref: "#/components/parameters/LayerExportId"
    get:
      operationId: downloadLayerExport
      responses:
        "200":
          description: Layered PSD file bytes.
        "404":
          $ref: "#/components/responses/NotFound"
  /files/layer-exports/{layerExportId}/layers/{layerIndex}:
    parameters:
      - $ref: "#/components/parameters/LayerExportId"
      - name: layerIndex
        in: path
        required: true
        schema:
          type: integer
          minimum: 0
    get:
      operationId: downloadLayerExportLayer
      responses:
        "200":
          description: Single layer PNG bytes.
        "404":
          $ref: "#/components/responses/NotFound"
  /events:
    get:
      operationId: subscribeEvents
      parameters:
        - name: projectId
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Server-sent event stream.
          content:
            text/event-stream:
              schema:
                type: string
components:
  parameters:
    ProviderId:
      name: providerId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ProjectId:
      name: projectId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    AssetId:
      name: assetId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    StoryboardItemId:
      name: itemId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    JobId:
      name: jobId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    OutputId:
      name: outputId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ExportId:
      name: exportId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    LayerExportId:
      name: layerExportId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    UserTemplateId:
      name: templateId
      in: path
      required: true
      schema:
        type: string
        pattern: ^custom-[0-9a-f]{8}$
    SuiteId:
      name: suiteId
      in: path
      required: true
      schema:
        type: string
        pattern: ^[a-z0-9][a-z0-9._-]{0,127}$
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
  responses:
    ValidationError:
      description: Request does not match the schema.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Conflict:
      description: Current resource state rejects this operation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    CapabilityUnsupported:
      description: The selected model lacks a requested capability.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ProviderError:
      description: Provider connectivity or protocol failure.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    PlatformTarget:
      type: string
      enum:
        - TAOBAO
        - JD
        - PDD
        - DOUYIN
        - AMAZON
        - SHOPIFY
    TargetMarket:
      type: string
      enum:
        - CHINA_MAINLAND
        - HONG_KONG
        - MACAU
        - TAIWAN
        - UNITED_STATES
        - UNITED_KINGDOM
        - GERMANY
        - FRANCE
        - ITALY
        - SPAIN
        - JAPAN
        - SOUTH_KOREA
    StoryboardMode:
      type: string
      enum:
        - CREATIVE
        - PIXEL_PROTECTED
    StoryboardShotRole:
      type: string
      enum:
        - HERO
        - PAIN_POINT
        - COMPARISON
        - SCENE
        - DETAIL
        - TRUST
        - VARIANT
        - CTA
    AssetRole:
      type: string
      enum:
        - PRODUCT_TRUTH
        - PACKAGING
        - STYLE_REFERENCE
        - LAYOUT_REFERENCE
    UserAssetKind:
      type: string
      enum:
        - PRODUCT
        - REFERENCE
    LibraryItemSource:
      type: string
      enum:
        - UPLOADED
        - GENERATED
    LibraryItemKind:
      type: string
      enum:
        - PRODUCT
        - REFERENCE
        - GENERATED
        - LAYER
    ImageResolution:
      type: string
      enum:
        - 1K
        - 2K
        - 4K
    ImageAspectRatio:
      type: string
      enum:
        - AUTO
        - 1:1
        - 2:3
        - 3:2
        - 3:4
        - 4:3
        - 4:5
        - 5:4
        - 9:16
        - 16:9
        - 21:9
    PlanningMode:
      type: string
      enum:
        - AI
        - MANUAL
    CopywritingTarget:
      type: string
      enum:
        - PRODUCT_DESCRIPTION
        - PLANNING_INSTRUCTION
    JobType:
      type: string
      enum:
        - PLAN
        - COPYWRITE
        - GENERATE
        - EXPORT
        - EDIT_PLAN
        - EDIT_GENERATE
        - LAYER_PLAN
        - LAYER_EXPORT
        - SUITE_FORGE
    JobStatus:
      type: string
      enum:
        - QUEUED
        - RUNNING
        - SUCCEEDED
        - FAILED
        - CANCELLED
    ReasoningProtocolProfile:
      type: string
      enum:
        - openai
        - dashscope_qwen
        - openai_responses
    SearchSourceKind:
      type: string
      enum:
        - brave
        - tavily
        - searxng
    EcomSuiteOrigin:
      type: string
      enum:
        - builtin
        - user
    EditOperation:
      type: string
      enum:
        - PRECISE_INPAINT
        - PRODUCT_REPLACE
        - SCENE_ADJUST
        - OUTPAINT
        - NATURAL_FUSION
    EditExecutionMode:
      type: string
      enum:
        - MODEL_DIRECTED
        - MASKED
        - OUTPAINT
        - NEED_INPUT
    CompositePolicy:
      type: string
      enum:
        - MASK_LOCKED
        - NATURAL_BLEND
        - OUTPAINT
        - PROVIDER_RESULT
    ReferenceSource:
      type: string
      enum:
        - PROJECT
        - TEMPORARY
    ReferencePurpose:
      type: string
      enum:
        - PRODUCT_APPEARANCE
        - PACKAGING
        - LABEL
        - STYLE
        - LAYOUT
    EditTurnStatus:
      type: string
      enum:
        - DRAFT
        - PLANNING
        - PLAN_READY
        - NEED_INPUT
        - AWAITING_CONFIRMATION
        - GENERATING
        - SUCCEEDED
        - FAILED
        - CANCELLED
    EditSessionStatus:
      type: string
      enum:
        - ACTIVE
        - ARCHIVED
    ErrorCode:
      type: string
      enum:
        - VALIDATION_ERROR
        - NOT_FOUND
        - CONFLICT
        - CAPABILITY_UNSUPPORTED
        - PROVIDER_NOT_CONFIGURED
        - RATE_LIMITED
        - INTERNAL_ERROR
        - PROVIDER_ERROR
    EventEnvelope:
      type: object
      required:
        - id
        - type
        - projectId
        - occurredAt
        - data
      properties:
        id:
          format: uuid
          type: string
        type:
          type: string
          enum:
            - job.updated
            - storyboard.updated
            - output.created
            - edit-session.updated
            - edit-turn.updated
            - export.updated
            - provider.updated
            - layer-plan.updated
            - layer-export.updated
        projectId:
          format: uuid
          type: string
        occurredAt:
          format: date-time
          type: string
        data: {}
    ModelCapabilities:
      type: object
      required:
        - supportsVision
        - supportsThinking
        - supportsTools
        - supportsStructuredOutput
        - imageApiKind
      properties:
        supportsVision:
          type: boolean
        supportsThinking:
          type: boolean
        supportsTools:
          type: boolean
        supportsStructuredOutput:
          type: boolean
        imageApiKind:
          anyOf:
            - const: openai_images
              type: string
            - const: gemini
              type: string
            - const: custom
              type: string
            - type: "null"
        segmentationProtocol:
          description: Segmentation API protocol declared for this model; mutually exclusive with imageApiKind.
          type: string
          enum:
            - fal
            - grounded_sam
            - seedream_layerize
            - gitee_sam3
    ModelDefinition:
      type: object
      allOf:
        - type: object
          required:
            - id
          properties:
            id:
              minLength: 1
              type: string
        - type: object
          required:
            - supportsVision
            - supportsThinking
            - supportsTools
            - supportsStructuredOutput
            - imageApiKind
          properties:
            supportsVision:
              type: boolean
            supportsThinking:
              type: boolean
            supportsTools:
              type: boolean
            supportsStructuredOutput:
              type: boolean
            imageApiKind:
              anyOf:
                - const: openai_images
                  type: string
                - const: gemini
                  type: string
                - const: custom
                  type: string
                - type: "null"
            segmentationProtocol:
              description: Segmentation API protocol declared for this model; mutually exclusive with imageApiKind.
              type: string
              enum:
                - fal
                - grounded_sam
                - seedream_layerize
                - gitee_sam3
    Asset:
      type: object
      required:
        - id
        - projectId
        - role
        - mimeType
        - createdAt
      properties:
        id:
          format: uuid
          type: string
        projectId:
          format: uuid
          type: string
        role:
          $ref: "#/components/schemas/AssetRole"
        kind:
          $ref: "#/components/schemas/UserAssetKind"
        url:
          type: string
        storagePath:
          type: string
        mimeType:
          type: string
        originalName:
          type: string
        hash:
          type: string
        width:
          anyOf:
            - type: integer
            - type: "null"
        height:
          anyOf:
            - type: integer
            - type: "null"
        createdAt:
          format: date-time
          type: string
    AssetList:
      type: object
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Asset"
        nextCursor:
          anyOf:
            - type: string
            - type: "null"
    CopywritingResult:
      type: object
      required:
        - jobId
        - projectId
        - target
        - content
        - createdAt
      properties:
        jobId:
          format: uuid
          type: string
        projectId:
          format: uuid
          type: string
        target:
          $ref: "#/components/schemas/CopywritingTarget"
        content:
          type: string
        createdAt:
          format: date-time
          type: string
    CreateCopywritingJobInput:
      type: object
      required:
        - target
        - regenerationKey
      properties:
        target:
          $ref: "#/components/schemas/CopywritingTarget"
        regenerationKey:
          description: Unique key for an intentional copywriting run.
          minLength: 1
          type: string
    CreateExportJobInput:
      type: object
      properties:
        outputIds:
          type: array
          items:
            format: uuid
            type: string
        filenamePrefix:
          type: string
        platformTargets:
          type: array
          items:
            type: string
            enum:
              - TAOBAO
              - JD
              - PDD
              - DOUYIN
              - AMAZON
              - SHOPIFY
        includeDetailPageSlices:
          default: false
          type: boolean
    CreatePlanningJobInput:
      type: object
      properties:
        planningMode:
          $ref: "#/components/schemas/PlanningMode"
        requestedTypes:
          type: array
          items:
            type: string
        requestedSuiteShots:
          maxItems: 12
          description: 套图分镜 assetType 列表（<suiteId>::<shotId>，仅手动规划使用）；每个分镜生成一条分镜，可与 requestedTypes 混选。
          type: array
          items:
            minLength: 1
            type: string
        imageTypes:
          type: array
          items:
            type: string
        userInstruction:
          maxLength: 4000
          type: string
        candidatesPerType:
          minimum: 1
          maximum: 4
          type: integer
        targetImageCount:
          minimum: 1
          maximum: 12
          type: integer
        imageResolution:
          $ref: "#/components/schemas/ImageResolution"
        imageAspectRatio:
          $ref: "#/components/schemas/ImageAspectRatio"
        regenerationKey:
          description: Unique key for an intentional re-planning run.
          minLength: 1
          type: string
    CreateProjectInput:
      type: object
      required:
        - name
        - reasoningProviderId
        - reasoningModelId
        - imageProviderId
        - imageModelId
        - defaultMode
      properties:
        name:
          minLength: 1
          type: string
        category:
          anyOf:
            - type: string
            - type: "null"
        productDescription:
          anyOf:
            - type: string
            - type: "null"
        verifiedFacts:
          type: array
          items:
            type: string
        prohibitedClaims:
          type: array
          items:
            type: string
        brandGuidelines:
          type: object
          patternProperties:
            ^(.*)$: {}
        platformTargets:
          maxItems: 1
          type: array
          items:
            type: string
            enum:
              - TAOBAO
              - JD
              - PDD
              - DOUYIN
              - AMAZON
              - SHOPIFY
        targetMarket:
          anyOf:
            - const: CHINA_MAINLAND
              type: string
            - const: HONG_KONG
              type: string
            - const: MACAU
              type: string
            - const: TAIWAN
              type: string
            - const: UNITED_STATES
              type: string
            - const: UNITED_KINGDOM
              type: string
            - const: GERMANY
              type: string
            - const: FRANCE
              type: string
            - const: ITALY
              type: string
            - const: SPAIN
              type: string
            - const: JAPAN
              type: string
            - const: SOUTH_KOREA
              type: string
            - type: "null"
        copyLanguage:
          anyOf:
            - minLength: 1
              maxLength: 64
              type: string
            - type: "null"
        reasoningProviderId:
          format: uuid
          type: string
        reasoningModelId:
          type: string
        imageProviderId:
          format: uuid
          type: string
        imageModelId:
          type: string
        segmentationModel:
          anyOf:
            - $ref: "#/components/schemas/SegmentationModelRef"
            - type: "null"
        defaultMode:
          type: string
          enum:
            - CREATIVE
            - PIXEL_PROTECTED
        imageResolution:
          $ref: "#/components/schemas/ImageResolution"
        imageAspectRatio:
          $ref: "#/components/schemas/ImageAspectRatio"
        candidatesPerType:
          minimum: 1
          maximum: 4
          type: integer
        webResearchEnabled:
          description: Enable restricted visual-direction web research during Agent planning.
          type: boolean
    CreateProviderInput:
      type: object
      required:
        - name
        - baseUrl
        - reasoningProtocol
        - apiKey
        - models
      properties:
        name:
          minLength: 1
          type: string
        baseUrl:
          format: uri
          type: string
        reasoningProtocol:
          type: string
          enum:
            - openai
            - dashscope_qwen
            - openai_responses
        apiKey:
          minLength: 1
          type: string
        models:
          minItems: 1
          type: array
          items:
            $ref: "#/components/schemas/ModelCapability"
    CreateSearchSourceInput:
      type: object
      required:
        - name
        - kind
        - priority
      properties:
        name:
          minLength: 1
          type: string
        kind:
          $ref: "#/components/schemas/SearchSourceKind"
        baseUrl:
          format: uri
          type: string
        apiKey:
          minLength: 1
          type: string
        priority:
          minimum: 0
          maximum: 100000
          type: integer
        enabled:
          default: true
          type: boolean
    CreateUserTemplateInput:
      type: object
      required:
        - name
        - prompt
      properties:
        name:
          minLength: 1
          maxLength: 40
          type: string
        prompt:
          minLength: 1
          maxLength: 20000
          description: Complete prompt template text. It is planning input with the same shape as built-in prompt_template entries and is injected into the planner payload; the planning Agent rewrites it into promptInstruction, which keeps its own 4000 budget. The 20000 bound is a generous planner-context sanity limit, not the final-prompt budget.
          type: string
        defaultSize:
          default: 1024x1024
          type: string
          enum:
            - 1024x1024
            - 1024x1536
        supportsImageReference:
          default: true
          type: boolean
    EcomSuiteCategoriesResponse:
      type: object
      required:
        - l1
        - l2
      properties:
        l1:
          type: array
          items:
            type: string
        l2:
          type: object
          patternProperties:
            ^(.*)$:
              type: array
              items:
                type: string
    EcomSuiteDetail:
      allOf:
        - $ref: "#/components/schemas/EcomSuiteFile"
        - type: object
          required:
            - origin
          properties:
            origin:
              $ref: "#/components/schemas/EcomSuiteOrigin"
            createdAt:
              format: date-time
              type: string
            updatedAt:
              format: date-time
              type: string
    EcomSuiteFile:
      type: object
      required:
        - name
        - category
        - styleLock
        - shots
      properties:
        schemaVersion:
          minimum: 1
          default: 1
          type: integer
        kind:
          default: ecomgen.suite
          const: ecomgen.suite
          type: string
        id:
          type: string
        name:
          minLength: 1
          maxLength: 60
          type: string
        description:
          maxLength: 400
          type: string
        category:
          $ref: "#/components/schemas/SuiteCategory"
        productFamily:
          type: string
        keywords:
          type: array
          items:
            type: string
        styleLock:
          $ref: "#/components/schemas/SuiteStyleLock"
        shots:
          minItems: 1
          maxItems: 12
          type: array
          items:
            $ref: "#/components/schemas/EcomSuiteShot"
        provenance:
          type: object
          properties:
            sourceKind:
              type: string
            sourceImageCount:
              minimum: 0
              type: integer
            detached:
              type: boolean
            notes:
              type: string
    EcomSuiteShot:
      type: object
      required:
        - shotId
        - order
        - shotRole
        - displayName
        - promptTemplate
      properties:
        shotId:
          minLength: 1
          maxLength: 64
          type: string
        order:
          minimum: 1
          type: integer
        shotRole:
          $ref: "#/components/schemas/StoryboardShotRole"
        displayName:
          minLength: 1
          type: string
        intent:
          type: string
        assetType:
          description: 服务端派生为 <suiteId>::<shotId>，上传文件可省略。
          type: string
        mode:
          type: string
          enum:
            - CREATIVE
            - PIXEL_PROTECTED
        aspectRatio:
          $ref: "#/components/schemas/ImageAspectRatio"
        resolution:
          $ref: "#/components/schemas/ImageResolution"
        camera:
          type: string
        lighting:
          type: string
        background:
          type: string
        props:
          type: string
        productOccupancy:
          type: string
        whitespace:
          type: string
        textZone:
          type: string
        promptTemplate:
          minLength: 1
          type: string
        supportsImageReference:
          default: true
          type: boolean
    EcomSuiteShotSummary:
      type: object
      required:
        - shotId
        - order
        - shotRole
        - displayName
      properties:
        shotId:
          type: string
        order:
          type: integer
        shotRole:
          $ref: "#/components/schemas/StoryboardShotRole"
        displayName:
          type: string
    EcomSuiteSummary:
      type: object
      required:
        - id
        - name
        - category
        - shotCount
        - shots
        - origin
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        category:
          $ref: "#/components/schemas/SuiteCategory"
        productFamily:
          type: string
        shotCount:
          minimum: 1
          type: integer
        shots:
          type: array
          items:
            $ref: "#/components/schemas/EcomSuiteShotSummary"
        origin:
          $ref: "#/components/schemas/EcomSuiteOrigin"
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
    EcomSuitesResponse:
      type: object
      required:
        - items
        - nextCursor
        - total
        - l1Counts
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/EcomSuiteSummary"
        nextCursor:
          description: Keyset cursor for the next page; null when the query is exhausted or no pagination applies.
          anyOf:
            - type: string
            - type: "null"
        total:
          minimum: 0
          description: Suite count of the whole catalog, independent of query filters.
          type: integer
        l1Counts:
          description: Per-L1 suite counts over the whole catalog, independent of query filters.
          type: object
          patternProperties:
            ^(.*)$:
              minimum: 0
              type: integer
    EditReferenceAsset:
      type: object
      required:
        - id
        - source
        - purpose
        - originalName
        - mimeType
        - hash
        - createdAt
        - url
      properties:
        id:
          format: uuid
          type: string
        source:
          $ref: "#/components/schemas/ReferenceSource"
        purpose:
          $ref: "#/components/schemas/ReferencePurpose"
        role:
          anyOf:
            - $ref: "#/components/schemas/AssetRole"
            - type: "null"
        originalName:
          type: string
        mimeType:
          type: string
        hash:
          type: string
        createdAt:
          format: date-time
          type: string
        expiresAt:
          anyOf:
            - format: date-time
              type: string
            - type: "null"
        url:
          type: string
    EditSession:
      type: object
      required:
        - id
        - projectId
        - currentOutputId
        - status
        - memorySummary
        - createdAt
        - updatedAt
      properties:
        id:
          format: uuid
          type: string
        projectId:
          format: uuid
          type: string
        currentOutputId:
          format: uuid
          type: string
        status:
          type: string
          enum:
            - ACTIVE
            - ARCHIVED
        memorySummary:
          type: object
          properties:
            summary:
              type: string
            constraints:
              type: array
              items:
                type: string
            sourceOutputId:
              description: Output node that owns the effective branch memory.
              format: uuid
              type: string
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
    EditTurn:
      type: object
      required:
        - id
        - sessionId
        - projectId
        - baseOutputId
        - status
        - message
        - annotations
        - referenceAssetIds
        - referenceSelections
        - createdAt
        - updatedAt
      properties:
        id:
          format: uuid
          type: string
        sessionId:
          format: uuid
          type: string
        projectId:
          format: uuid
          type: string
        baseOutputId:
          format: uuid
          type: string
        status:
          $ref: "#/components/schemas/EditTurnStatus"
        message:
          type: string
        annotations:
          type: object
          patternProperties:
            ^(.*)$: {}
        editMaskPath:
          anyOf:
            - type: string
            - type: "null"
        protectMaskPath:
          anyOf:
            - type: string
            - type: "null"
        referenceAssetIds:
          type: array
          items:
            format: uuid
            type: string
        referenceSelections:
          type: array
          items:
            $ref: "#/components/schemas/ReferenceSelection"
        plan:
          anyOf:
            - type: object
              properties:
                operation:
                  $ref: "#/components/schemas/EditOperation"
                executionMode:
                  $ref: "#/components/schemas/EditExecutionMode"
                userSummary:
                  type: string
                prompt:
                  type: string
                targetAnnotationIds:
                  type: array
                  items:
                    type: string
                targetDescription:
                  type: string
                targetConfidence:
                  minimum: 0
                  maximum: 1
                  type: number
                clarification:
                  anyOf:
                    - type: string
                    - type: "null"
                requiresConfirmation:
                  type: boolean
                compositePolicy:
                  $ref: "#/components/schemas/CompositePolicy"
                memoryPatch:
                  type: object
                  patternProperties:
                    ^(.*)$: {}
            - type: "null"
        error:
          anyOf:
            - type: object
              patternProperties:
                ^(.*)$: {}
            - type: "null"
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - requestId
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: array
              items:
                type: object
                patternProperties:
                  ^(.*)$: {}
            requestId:
              format: uuid
              type: string
    Export:
      type: object
      required:
        - id
        - projectId
        - status
        - createdAt
      properties:
        id:
          format: uuid
          type: string
        projectId:
          format: uuid
          type: string
        jobId:
          format: uuid
          type: string
        status:
          type: string
          enum:
            - QUEUED
            - RUNNING
            - SUCCEEDED
            - FAILED
        storagePath:
          anyOf:
            - type: string
            - type: "null"
        downloadUrl:
          anyOf:
            - type: string
            - type: "null"
        createdAt:
          format: date-time
          type: string
    ExportJobBundle:
      type: object
      required:
        - job
        - export
      properties:
        job:
          $ref: "#/components/schemas/Job"
        export:
          anyOf:
            - type: object
              patternProperties:
                ^(.*)$: {}
            - type: "null"
    Health:
      type: object
      required:
        - status
        - webResearchAvailable
      properties:
        status:
          type: string
        webResearchAvailable:
          description: Whether the server has a configured restricted visual-research search key.
          type: boolean
    Job:
      type: object
      required:
        - id
        - type
        - status
        - progress
        - retryable
        - createdAt
      properties:
        id:
          format: uuid
          type: string
        type:
          type: string
          enum:
            - PLAN
            - COPYWRITE
            - GENERATE
            - EXPORT
            - EDIT_PLAN
            - EDIT_GENERATE
            - LAYER_PLAN
            - LAYER_EXPORT
            - SUITE_FORGE
        status:
          type: string
          enum:
            - QUEUED
            - RUNNING
            - SUCCEEDED
            - FAILED
            - CANCELLED
        progress:
          minimum: 0
          maximum: 100
          type: integer
        retryable:
          type: boolean
        requestFingerprint:
          anyOf:
            - type: string
            - type: "null"
        providerId:
          anyOf:
            - format: uuid
              type: string
            - type: "null"
        modelId:
          anyOf:
            - type: string
            - type: "null"
        estimatedCost:
          anyOf:
            - type: object
              patternProperties:
                ^(.*)$: {}
            - type: "null"
        actualCost:
          anyOf:
            - type: object
              patternProperties:
                ^(.*)$: {}
            - type: "null"
        cancelRequested:
          type: boolean
        error:
          anyOf:
            - type: object
              patternProperties:
                ^(.*)$: {}
            - type: "null"
        progressDetail:
          anyOf:
            - $ref: "#/components/schemas/JobProgressDetail"
            - type: "null"
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
    JobProgressDetail:
      type: object
      required:
        - shotsGenerated
        - shotsTarget
      properties:
        shotsGenerated:
          minimum: 0
          description: 流式观察到的已生成分镜数（模型可能回填或重试，不保证单调）。
          type: integer
        shotsTarget:
          description: 建单时指定的目标分镜数；未指定时为 null，此时只有分子没有分母。
          anyOf:
            - minimum: 1
              type: integer
            - type: "null"
    LayerBbox:
      description: Normalized bounding box relative to the output image.
      type: object
      required:
        - x
        - y
        - width
        - height
      properties:
        x:
          minimum: 0
          maximum: 1
          type: number
        y:
          minimum: 0
          maximum: 1
          type: number
        width:
          exclusiveMinimum: 0
          maximum: 1
          type: number
        height:
          exclusiveMinimum: 0
          maximum: 1
          type: number
    LayerExport:
      type: object
      required:
        - id
        - projectId
        - outputId
        - jobId
        - status
        - includeBackground
        - createdAt
        - updatedAt
      properties:
        id:
          format: uuid
          type: string
        projectId:
          format: uuid
          type: string
        outputId:
          format: uuid
          type: string
        jobId:
          format: uuid
          type: string
        planId:
          anyOf:
            - format: uuid
              type: string
            - type: "null"
        status:
          type: string
          enum:
            - QUEUED
            - RUNNING
            - SUCCEEDED
            - FAILED
            - CANCELLED
        includeBackground:
          description: "Whether a background layer is produced under the element layers: Seedream uses its inpainted base image; SAM protocols use the original image with the element selections cut out (holed)."
          type: boolean
        psdStoragePath:
          anyOf:
            - type: string
            - type: "null"
        psdDownloadUrl:
          anyOf:
            - type: string
            - type: "null"
        layerFiles:
          anyOf:
            - type: array
              items:
                $ref: "#/components/schemas/LayerExportLayerFile"
            - type: "null"
        error:
          anyOf:
            - type: object
              patternProperties:
                ^(.*)$: {}
            - type: "null"
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
    LayerExportBundle:
      type: object
      required:
        - job
        - layerExport
      properties:
        job:
          $ref: "#/components/schemas/Job"
        layerExport:
          $ref: "#/components/schemas/LayerExport"
    LayerExportHistory:
      type: object
      required:
        - exports
      properties:
        exports:
          description: Layer exports of the output, newest first. Earlier records stay viewable and downloadable after a newer export replaces the latest one.
          type: array
          items:
            $ref: "#/components/schemas/LayerExport"
    LayerExportLayerFile:
      type: object
      required:
        - name
        - kind
        - downloadUrl
      properties:
        name:
          type: string
        kind:
          type: string
          enum:
            - element
            - background
            - composite
        downloadUrl:
          type: string
    LayerPlan:
      type: object
      required:
        - id
        - projectId
        - outputId
        - jobId
        - outputHash
        - status
        - elements
        - createdAt
        - updatedAt
      properties:
        id:
          format: uuid
          type: string
        projectId:
          format: uuid
          type: string
        outputId:
          format: uuid
          type: string
        jobId:
          format: uuid
          type: string
        outputHash:
          description: Content hash of the output image; the plan is reused while this matches the current output and the reasoning model snapshot.
          type: string
        status:
          type: string
          enum:
            - QUEUED
            - RUNNING
            - SUCCEEDED
            - FAILED
            - CANCELLED
        elements:
          type: array
          items:
            $ref: "#/components/schemas/LayerPlanElement"
        error:
          anyOf:
            - type: object
              patternProperties:
                ^(.*)$: {}
            - type: "null"
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
    LayerPlanElement:
      type: object
      required:
        - id
        - name
        - source
      properties:
        id:
          description: Stable element ID inside the plan; manual elements reuse the client-provided ID.
          type: string
        name:
          description: Editable element display name.
          type: string
        promptEn:
          description: English segmentation prompt recognized with the element; used by text-prompt-only segmentation channels such as Gitee AI SAM 3.
          type: string
        source:
          type: string
          enum:
            - auto
            - manual
        bbox:
          anyOf:
            - $ref: "#/components/schemas/LayerBbox"
            - type: "null"
    LibraryAsset:
      type: object
      required:
        - id
        - source
        - kind
        - name
        - projectId
        - projectName
        - mimeType
        - hash
        - url
        - thumbnailUrl
        - createdAt
      properties:
        id:
          description: "Synthetic library item ID: 'asset:<uuid>' or 'output:<uuid>'."
          type: string
        source:
          $ref: "#/components/schemas/LibraryItemSource"
        kind:
          $ref: "#/components/schemas/LibraryItemKind"
        name:
          type: string
        projectId:
          format: uuid
          type: string
        projectName:
          type: string
        mimeType:
          type: string
        hash:
          type: string
        width:
          anyOf:
            - type: integer
            - type: "null"
        height:
          anyOf:
            - type: integer
            - type: "null"
        url:
          type: string
        thumbnailUrl:
          type: string
        createdAt:
          format: date-time
          type: string
        role:
          anyOf:
            - $ref: "#/components/schemas/AssetRole"
            - type: "null"
    LibraryAssetList:
      type: object
      required:
        - items
        - nextCursor
        - total
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/LibraryAsset"
        nextCursor:
          anyOf:
            - type: string
            - type: "null"
        total:
          minimum: 0
          type: integer
    ModelCapability:
      type: object
      required:
        - id
        - supportsVision
        - supportsThinking
        - supportsTools
        - supportsStructuredOutput
      properties:
        id:
          type: string
        supportsVision:
          type: boolean
        supportsThinking:
          type: boolean
        supportsTools:
          type: boolean
        supportsStructuredOutput:
          type: boolean
        imageApiKind:
          anyOf:
            - const: openai_images
              type: string
            - const: gemini
              type: string
            - const: custom
              type: string
            - type: "null"
        segmentationProtocol:
          description: Segmentation API protocol declared for this model (fal.ai SAM 3, self-hosted Grounded-SAM, Volcengine Seedream layer decomposition, or Gitee AI SAM 3 pipeline); mutually exclusive with imageApiKind.
          type: string
          enum:
            - fal
            - grounded_sam
            - seedream_layerize
            - gitee_sam3
    ModelRef:
      type: object
      required:
        - providerId
        - modelId
      properties:
        providerId:
          format: uuid
          type: string
        modelId:
          type: string
    Output:
      type: object
      required:
        - id
        - storyboardItemId
        - jobId
        - createdAt
      properties:
        id:
          format: uuid
          type: string
        storyboardItemId:
          format: uuid
          type: string
        jobId:
          format: uuid
          type: string
        candidateIndex:
          minimum: 1
          type: integer
        generationSnapshot:
          anyOf:
            - type: object
              properties:
                providerId:
                  format: uuid
                  type: string
                modelId:
                  type: string
                resolution:
                  $ref: "#/components/schemas/ImageResolution"
                aspectRatio:
                  $ref: "#/components/schemas/ImageAspectRatio"
                size:
                  type: string
                candidateIndex:
                  minimum: 1
                  type: integer
                revision:
                  type: string
            - type: "null"
        url:
          type: string
        storagePath:
          type: string
        parentOutputId:
          anyOf:
            - format: uuid
              type: string
            - type: "null"
        rootOutputId:
          anyOf:
            - format: uuid
              type: string
            - type: "null"
        editSessionId:
          anyOf:
            - format: uuid
              type: string
            - type: "null"
        editTurnId:
          anyOf:
            - format: uuid
              type: string
            - type: "null"
        generationBatchId:
          anyOf:
            - format: uuid
              type: string
            - type: "null"
        createdAt:
          format: date-time
          type: string
    PlanningConfigSnapshot:
      type: object
      required:
        - id
        - projectId
        - sourceJobId
        - payload
        - createdAt
      properties:
        id:
          format: uuid
          type: string
        projectId:
          format: uuid
          type: string
        sourceJobId:
          format: uuid
          type: string
        payload:
          type: object
          patternProperties:
            ^(.*)$: {}
        createdAt:
          format: date-time
          type: string
    Project:
      type: object
      required:
        - id
        - name
        - platformTargets
        - targetMarket
        - copyLanguage
        - reasoningProviderId
        - reasoningModelId
        - imageProviderId
        - imageModelId
        - defaultMode
        - imageResolution
        - imageAspectRatio
        - candidatesPerType
        - webResearchEnabled
        - createdAt
        - updatedAt
      properties:
        id:
          format: uuid
          type: string
        name:
          type: string
        category:
          anyOf:
            - type: string
            - type: "null"
        productDescription:
          anyOf:
            - type: string
            - type: "null"
        verifiedFacts:
          type: array
          items:
            type: string
        prohibitedClaims:
          type: array
          items:
            type: string
        brandGuidelines:
          type: object
          patternProperties:
            ^(.*)$: {}
        platformTargets:
          maxItems: 1
          type: array
          items:
            type: string
            enum:
              - TAOBAO
              - JD
              - PDD
              - DOUYIN
              - AMAZON
              - SHOPIFY
        targetMarket:
          anyOf:
            - const: CHINA_MAINLAND
              type: string
            - const: HONG_KONG
              type: string
            - const: MACAU
              type: string
            - const: TAIWAN
              type: string
            - const: UNITED_STATES
              type: string
            - const: UNITED_KINGDOM
              type: string
            - const: GERMANY
              type: string
            - const: FRANCE
              type: string
            - const: ITALY
              type: string
            - const: SPAIN
              type: string
            - const: JAPAN
              type: string
            - const: SOUTH_KOREA
              type: string
            - type: "null"
        copyLanguage:
          anyOf:
            - minLength: 1
              maxLength: 64
              type: string
            - type: "null"
        reasoningProviderId:
          anyOf:
            - format: uuid
              type: string
            - type: "null"
        reasoningModelId:
          anyOf:
            - type: string
            - type: "null"
        imageProviderId:
          anyOf:
            - format: uuid
              type: string
            - type: "null"
        imageModelId:
          anyOf:
            - type: string
            - type: "null"
        segmentationModel:
          anyOf:
            - $ref: "#/components/schemas/SegmentationModelRef"
            - type: "null"
        defaultMode:
          type: string
          enum:
            - CREATIVE
            - PIXEL_PROTECTED
        imageResolution:
          $ref: "#/components/schemas/ImageResolution"
        imageAspectRatio:
          $ref: "#/components/schemas/ImageAspectRatio"
        candidatesPerType:
          minimum: 1
          maximum: 4
          type: integer
        webResearchEnabled:
          description: Enable restricted visual-direction web research during Agent planning.
          type: boolean
        archivedAt:
          anyOf:
            - format: date-time
              type: string
            - type: "null"
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
        cover:
          $ref: "#/components/schemas/ProjectCover"
    ProjectCover:
      type: object
      required:
        - productAssetId
        - coverOutputId
        - previewOutputIds
        - outputCount
      properties:
        productAssetId:
          anyOf:
            - format: uuid
              type: string
            - type: "null"
        coverOutputId:
          anyOf:
            - format: uuid
              type: string
            - type: "null"
        previewOutputIds:
          type: array
          items:
            format: uuid
            type: string
        outputCount:
          minimum: 0
          type: integer
    ProjectDetail:
      allOf:
        - $ref: "#/components/schemas/Project"
        - type: object
          required:
            - assets
            - storyboard
            - items
            - outputs
            - jobs
          properties:
            assets:
              type: array
              items:
                $ref: "#/components/schemas/Asset"
            storyboard:
              anyOf:
                - type: object
                  patternProperties:
                    ^(.*)$: {}
                - type: "null"
            items:
              type: array
              items:
                $ref: "#/components/schemas/StoryboardItem"
            outputs:
              type: array
              items:
                $ref: "#/components/schemas/Output"
            jobs:
              type: array
              items:
                $ref: "#/components/schemas/Job"
    ProjectList:
      type: object
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          items:
            allOf:
              - $ref: "#/components/schemas/Project"
              - type: object
                patternProperties:
                  ^(.*)$: {}
        nextCursor:
          anyOf:
            - type: string
            - type: "null"
    ProviderConfig:
      type: object
      required:
        - id
        - name
        - baseUrl
        - reasoningProtocol
        - hasApiKey
        - models
        - createdAt
        - updatedAt
      properties:
        id:
          format: uuid
          type: string
        name:
          type: string
        baseUrl:
          format: uri
          type: string
        reasoningProtocol:
          type: string
          enum:
            - openai
            - dashscope_qwen
            - openai_responses
        hasApiKey:
          type: boolean
        models:
          type: array
          items:
            $ref: "#/components/schemas/ModelCapability"
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
    ProviderList:
      type: object
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ProviderConfig"
        nextCursor:
          anyOf:
            - type: string
            - type: "null"
    ReferenceSelection:
      type: object
      required:
        - id
        - source
        - purpose
        - order
      properties:
        id:
          format: uuid
          type: string
        source:
          $ref: "#/components/schemas/ReferenceSource"
        purpose:
          $ref: "#/components/schemas/ReferencePurpose"
        order:
          minimum: 0
          type: integer
    SearchSourceConfig:
      type: object
      required:
        - id
        - name
        - kind
        - baseUrl
        - priority
        - enabled
        - hasApiKey
        - createdAt
        - updatedAt
      properties:
        id:
          format: uuid
          type: string
        name:
          type: string
        kind:
          $ref: "#/components/schemas/SearchSourceKind"
        baseUrl:
          format: uri
          type: string
        priority:
          description: Lower values are searched first.
          minimum: 0
          maximum: 100000
          type: integer
        enabled:
          type: boolean
        hasApiKey:
          type: boolean
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
    SearchSourceList:
      type: object
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/SearchSourceConfig"
        nextCursor:
          anyOf:
            - type: string
            - type: "null"
    SegmentationModelRef:
      description: Segmentation model reference; the referenced model must be declared as a segmentation model on its provider.
      type: object
      required:
        - providerId
        - modelId
      properties:
        providerId:
          format: uuid
          type: string
        modelId:
          type: string
        protocol:
          description: Segmentation API protocol; derived from the model's declared segmentationProtocol and re-stated here for the Worker adapter. A body protocol that contradicts the declared one is rejected.
          type: string
          enum:
            - fal
            - grounded_sam
            - seedream_layerize
            - gitee_sam3
    Storyboard:
      type: object
      required:
        - projectId
        - version
        - status
        - campaignStyleLock
      properties:
        projectId:
          format: uuid
          type: string
        version:
          minimum: 1
          type: integer
        status:
          type: string
          enum:
            - DRAFT
            - CONFIRMED
        campaignStyleLock:
          type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/StoryboardItem"
    StoryboardBundle:
      type: object
      required:
        - storyboard
        - items
      properties:
        storyboard:
          anyOf:
            - type: object
              patternProperties:
                ^(.*)$: {}
            - type: "null"
        items:
          type: array
          items:
            $ref: "#/components/schemas/StoryboardItem"
    StoryboardItem:
      type: object
      required:
        - id
        - assetType
        - displayName
        - candidateCount
        - mode
        - status
        - promptInstruction
        - riskFlags
      properties:
        id:
          format: uuid
          type: string
        assetType:
          description: Immutable ecom-details-image template ID; it cannot be changed after planning.
          type: string
        displayName:
          type: string
        shotRole:
          description: Visual-task semantics assigned during planning; immutable. Null on items planned before this field existed.
          anyOf:
            - $ref: "#/components/schemas/StoryboardShotRole"
            - type: "null"
        templateVariant:
          anyOf:
            - type: string
            - type: "null"
        candidateCount:
          minimum: 1
          maximum: 4
          type: integer
        imageProviderId:
          format: uuid
          type: string
        imageModelId:
          type: string
        imageResolution:
          $ref: "#/components/schemas/ImageResolution"
        imageAspectRatio:
          $ref: "#/components/schemas/ImageAspectRatio"
        referencedAssets:
          type: array
          items:
            format: uuid
            type: string
        mode:
          type: string
          enum:
            - CREATIVE
            - PIXEL_PROTECTED
        status:
          type: string
          enum:
            - DRAFT
            - CONFIRMED
            - GENERATING
            - GENERATED
        promptInstruction:
          description: Final image-generation prompt produced by Pi Agent. Must instruct the image model to preserve exact product identity. Worker prefixes selected image roles in their actual request order before sending it to the image model.
          type: string
        factClaims:
          type: array
          items:
            type: string
        riskFlags:
          type: array
          items:
            type: string
    SuiteCategory:
      type: object
      required:
        - l1
        - l2
        - leaf
      properties:
        l1:
          minLength: 1
          type: string
        l2:
          minLength: 1
          type: string
        leaf:
          minLength: 1
          type: string
        leafKeywords:
          type: array
          items:
            type: string
    SuitePaletteColor:
      type: object
      required:
        - name
        - hex
      properties:
        name:
          minLength: 1
          type: string
        hex:
          minLength: 1
          type: string
    SuiteStyleLock:
      type: object
      required:
        - lockText
      properties:
        direction:
          type: string
        palette:
          type: array
          items:
            $ref: "#/components/schemas/SuitePaletteColor"
        temperature:
          type: string
        backgroundSystem:
          type: string
        lightingSystem:
          type: string
        surfaceSystem:
          type: string
        typography:
          type: string
        iconSystem:
          type: string
        presentationRules:
          type: string
        noDrift:
          type: array
          items:
            type: string
        lockText:
          minLength: 1
          description: 整句风格锁文本，规划时按 {style_lock} 注入每条分镜 Prompt。
          type: string
    UpdateProjectInput:
      type: object
      properties:
        name:
          minLength: 1
          type: string
        category:
          anyOf:
            - type: string
            - type: "null"
        productDescription:
          anyOf:
            - type: string
            - type: "null"
        verifiedFacts:
          type: array
          items:
            type: string
        prohibitedClaims:
          type: array
          items:
            type: string
        brandGuidelines:
          type: object
          patternProperties:
            ^(.*)$: {}
        platformTargets:
          maxItems: 1
          type: array
          items:
            type: string
            enum:
              - TAOBAO
              - JD
              - PDD
              - DOUYIN
              - AMAZON
              - SHOPIFY
        targetMarket:
          anyOf:
            - const: CHINA_MAINLAND
              type: string
            - const: HONG_KONG
              type: string
            - const: MACAU
              type: string
            - const: TAIWAN
              type: string
            - const: UNITED_STATES
              type: string
            - const: UNITED_KINGDOM
              type: string
            - const: GERMANY
              type: string
            - const: FRANCE
              type: string
            - const: ITALY
              type: string
            - const: SPAIN
              type: string
            - const: JAPAN
              type: string
            - const: SOUTH_KOREA
              type: string
            - type: "null"
        copyLanguage:
          anyOf:
            - minLength: 1
              maxLength: 64
              type: string
            - type: "null"
        reasoningModel:
          $ref: "#/components/schemas/ModelRef"
        imageModel:
          $ref: "#/components/schemas/ModelRef"
        segmentationModel:
          anyOf:
            - $ref: "#/components/schemas/SegmentationModelRef"
            - type: "null"
        defaultMode:
          type: string
          enum:
            - CREATIVE
            - PIXEL_PROTECTED
        imageResolution:
          $ref: "#/components/schemas/ImageResolution"
        imageAspectRatio:
          $ref: "#/components/schemas/ImageAspectRatio"
        candidatesPerType:
          minimum: 1
          maximum: 4
          type: integer
        webResearchEnabled:
          description: Enable restricted visual-direction web research during Agent planning.
          type: boolean
        archived:
          description: Archive or restore the project.
          type: boolean
    UpdateProviderInput:
      type: object
      properties:
        name:
          minLength: 1
          type: string
        baseUrl:
          format: uri
          type: string
        reasoningProtocol:
          type: string
          enum:
            - openai
            - dashscope_qwen
            - openai_responses
        apiKey:
          minLength: 1
          type: string
        models:
          minItems: 1
          type: array
          items:
            $ref: "#/components/schemas/ModelCapability"
    UpdateSearchSourceInput:
      type: object
      properties:
        name:
          minLength: 1
          type: string
        kind:
          $ref: "#/components/schemas/SearchSourceKind"
        baseUrl:
          format: uri
          type: string
        apiKey:
          minLength: 1
          type: string
        priority:
          minimum: 0
          maximum: 100000
          type: integer
        enabled:
          type: boolean
    UpdateStoryboardItemInput:
      type: object
      properties:
        assetType:
          description: Immutable ecom-details-image template ID; it cannot be changed after planning.
          type: string
        displayName:
          type: string
        templateVariant:
          anyOf:
            - type: string
            - type: "null"
        candidateCount:
          minimum: 1
          maximum: 4
          type: integer
        imageModel:
          $ref: "#/components/schemas/ModelRef"
        imageResolution:
          $ref: "#/components/schemas/ImageResolution"
        imageAspectRatio:
          $ref: "#/components/schemas/ImageAspectRatio"
        referencedAssets:
          type: array
          items:
            format: uuid
            type: string
        mode:
          type: string
          enum:
            - CREATIVE
            - PIXEL_PROTECTED
        promptInstruction:
          description: Editable final image-generation prompt. Must keep instructing the image model to preserve exact product identity. Worker prefixes selected image roles in their actual request order before sending it to the image model.
          maxLength: 4000
          type: string
    UpdateUserTemplateInput:
      type: object
      properties:
        name:
          minLength: 1
          maxLength: 40
          type: string
        prompt:
          minLength: 1
          maxLength: 20000
          type: string
        defaultSize:
          type: string
          enum:
            - 1024x1024
            - 1024x1536
        supportsImageReference:
          type: boolean
    UserTemplateItem:
      type: object
      required:
        - id
        - name
        - prompt
        - defaultSize
        - supportsImageReference
        - createdAt
        - updatedAt
      properties:
        id:
          description: Server-generated custom template ID with the custom- prefix.
          type: string
        name:
          type: string
        prompt:
          description: Full prompt template text; may contain {placeholders} the planning agent rewrites from project context.
          type: string
        defaultSize:
          type: string
          enum:
            - 1024x1024
            - 1024x1536
        supportsImageReference:
          type: boolean
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
    UserTemplateList:
      type: object
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/UserTemplateItem"
        nextCursor:
          anyOf:
            - type: string
            - type: "null"
    AiPlanningInput:
      type: object
      properties:
        planningMode:
          $ref: "#/components/schemas/PlanningMode"
        requestedTypes:
          type: array
          items:
            type: string
        requestedSuiteShots:
          maxItems: 12
          type: array
          items:
            minLength: 1
            type: string
        imageTypes:
          type: array
          items:
            type: string
        userInstruction:
          maxLength: 4000
          type: string
        candidatesPerType:
          minimum: 1
          maximum: 4
          type: integer
        targetImageCount:
          minimum: 1
          maximum: 12
          type: integer
        imageResolution:
          $ref: "#/components/schemas/ImageResolution"
        imageAspectRatio:
          $ref: "#/components/schemas/ImageAspectRatio"
        regenerationKey:
          minLength: 1
          type: string
    ApplyPlanningConfigSnapshotResult:
      type: object
      required:
        - project
        - snapshot
      properties:
        project:
          $ref: "#/components/schemas/Project"
        snapshot:
          $ref: "#/components/schemas/PlanningConfigSnapshot"
    ApproveEditTurnResponse:
      type: object
      required:
        - job
        - turn
      properties:
        job:
          $ref: "#/components/schemas/Job"
        turn:
          $ref: "#/components/schemas/EditTurn"
    ConfirmStoryboardInput:
      type: object
      properties:
        version:
          minimum: 1
          type: integer
    CopyLibraryAssetToProjectInput:
      type: object
      required:
        - itemId
      properties:
        itemId:
          description: "Library item ID: 'asset:<uuid>' or 'output:<uuid>'."
          type: string
        role:
          $ref: "#/components/schemas/AssetRole"
        kind:
          $ref: "#/components/schemas/UserAssetKind"
    CreateEditTurnInput:
      type: object
      required:
        - message
      properties:
        baseOutputId:
          format: uuid
          type: string
        message:
          maxLength: 4000
          type: string
        annotations:
          type: string
        editMask:
          format: binary
          type: string
        protectMask:
          format: binary
          type: string
        referenceSelections:
          type: string
    CreateExportJobRequest:
      type: object
      properties:
        outputIds:
          type: array
          items:
            format: uuid
            type: string
        filenamePrefix:
          type: string
        platformTargets:
          type: array
          items:
            $ref: "#/components/schemas/PlatformTarget"
        includeDetailPageSlices:
          type: boolean
    CreateGenerationJobInput:
      type: object
      required:
        - storyboardItemIds
      properties:
        storyboardItemIds:
          minItems: 1
          type: array
          items:
            format: uuid
            type: string
        generationBatchId:
          format: uuid
          type: string
        revision:
          type: string
        generationConfig:
          type: object
          properties:
            imageResolution:
              $ref: "#/components/schemas/ImageResolution"
            imageAspectRatio:
              $ref: "#/components/schemas/ImageAspectRatio"
            candidateCount:
              minimum: 1
              maximum: 4
              type: integer
            imageModel:
              $ref: "#/components/schemas/ModelRef"
    CreateLayerExportElement:
      description: Manual elements must carry the normalized bbox drawn on the canvas; prompt elements come from user-typed element names and need no bbox or recognition plan.
      type: object
      required:
        - id
        - name
        - source
      properties:
        id:
          minLength: 1
          maxLength: 64
          type: string
        name:
          minLength: 1
          maxLength: 60
          type: string
        source:
          type: string
          enum:
            - auto
            - manual
            - prompt
        promptEn:
          minLength: 1
          maxLength: 80
          description: English segmentation prompt for auto elements; the API copies it from the referenced plan, so clients usually omit it.
          type: string
        bbox:
          $ref: "#/components/schemas/LayerBbox"
    CreateLayerExportInput:
      type: object
      required:
        - elements
      properties:
        elements:
          minItems: 1
          maxItems: 32
          type: array
          items:
            $ref: "#/components/schemas/CreateLayerExportElement"
        includeBackground:
          default: true
          description: Generate a holed background layer under the element layers.
          type: boolean
        planId:
          format: uuid
          description: The recognition plan the auto elements were selected from; rejected if the plan has since changed.
          type: string
    CreateLayerPlanInput:
      type: object
      properties:
        regenerationKey:
          minLength: 1
          description: Unique key for an intentional re-recognition run.
          type: string
    CreateSuiteForgeJobInput:
      type: object
      required:
        - providerId
        - modelId
        - files
      properties:
        providerId:
          format: uuid
          type: string
        modelId:
          minLength: 1
          type: string
        files:
          minItems: 1
          maxItems: 12
          description: 爆款套图源图，5–12 张为佳。
          type: array
          items:
            format: binary
            type: string
        name:
          minLength: 1
          maxLength: 60
          type: string
        l1:
          minLength: 1
          type: string
        l2:
          minLength: 1
          type: string
        leaf:
          minLength: 1
          type: string
        productFamily:
          type: string
        targetShotCount:
          minimum: 5
          maximum: 12
          type: integer
        userInstruction:
          maxLength: 4000
          description: 额外反推要求，例如只保留某个卖点结构。
          type: string
        idempotencyKey:
          minLength: 1
          type: string
    EcomTemplateItem:
      type: object
      required:
        - id
        - upstreamNumber
        - name
        - keywords
        - trigger_phrases
        - prompt_template
        - defaults
        - category_tips
        - defaultSize
      properties:
        id:
          type: string
        upstreamNumber:
          type: integer
        name:
          type: string
        keywords:
          type: array
          items:
            type: string
        trigger_phrases:
          type: array
          items:
            type: string
        prompt_template:
          type: object
          patternProperties:
            ^(.*)$:
              type: string
        defaults:
          type: object
          patternProperties:
            ^(.*)$:
              type: string
        category_tips:
          type: object
          patternProperties:
            ^(.*)$:
              type: string
        defaultSize:
          type: string
          enum:
            - 1024x1024
            - 1024x1536
        variants:
          type: object
          patternProperties:
            ^(.*)$: {}
    EcomTemplatesResponse:
      type: object
      required:
        - source
        - items
      properties:
        source:
          type: object
          required:
            - repository
            - commit
            - sourcePath
          properties:
            repository:
              format: uri
              type: string
            commit:
              type: string
            sourcePath:
              type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/EcomTemplateItem"
    EditGenerationConfigInput:
      type: object
      required:
        - reasoningProviderId
        - reasoningModelId
        - imageProviderId
        - imageModelId
      properties:
        reasoningProviderId:
          format: uuid
          type: string
        reasoningModelId:
          minLength: 1
          type: string
        imageProviderId:
          format: uuid
          type: string
        imageModelId:
          minLength: 1
          type: string
        imageResolution:
          $ref: "#/components/schemas/ImageResolution"
        candidateCount:
          minimum: 1
          maximum: 4
          type: integer
    EditReferenceAssetList:
      type: object
      required:
        - items
        - suggestedSelections
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/EditReferenceAsset"
        suggestedSelections:
          type: array
          items:
            $ref: "#/components/schemas/ReferenceSelection"
    EditTurnQueuedResponse:
      type: object
      required:
        - turnId
        - planJobId
        - status
      properties:
        turnId:
          format: uuid
          type: string
        planJobId:
          format: uuid
          type: string
        status:
          $ref: "#/components/schemas/EditTurnStatus"
    GenerationJobsResponse:
      type: object
      required:
        - jobs
      properties:
        jobs:
          type: array
          items:
            $ref: "#/components/schemas/Job"
    ManualPlanningInput:
      type: object
      required:
        - planningMode
      properties:
        planningMode:
          const: MANUAL
          type: string
        requestedTypes:
          minItems: 1
          type: array
          items:
            type: string
        requestedSuiteShots:
          maxItems: 12
          description: 手动规划必须提供 requestedTypes 与 requestedSuiteShots 中至少一项。
          type: array
          items:
            minLength: 1
            type: string
        userInstruction:
          maxLength: 4000
          type: string
        candidatesPerType:
          minimum: 1
          maximum: 4
          type: integer
        imageResolution:
          $ref: "#/components/schemas/ImageResolution"
        imageAspectRatio:
          $ref: "#/components/schemas/ImageAspectRatio"
        regenerationKey:
          minLength: 1
          type: string
    PlanningConfigSnapshotList:
      type: array
      items:
        $ref: "#/components/schemas/PlanningConfigSnapshot"
    SelectEditSessionOutputInput:
      type: object
      required:
        - outputId
      properties:
        outputId:
          format: uuid
          type: string
    SuiteForgeDraftSummary:
      type: object
      required:
        - name
        - l1
        - l2
        - leaf
        - shotCount
        - suiteId
      properties:
        name:
          type: string
        l1:
          type: string
        l2:
          type: string
        leaf:
          type: string
        shotCount:
          minimum: 0
          type: integer
        suiteId:
          description: 已入库的套图 ID；仍为草稿时为 null。
          anyOf:
            - type: string
            - type: "null"
    SuiteForgeJobList:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/SuiteForgeJobSummary"
    SuiteForgeJobSummary:
      type: object
      required:
        - jobId
        - status
        - progress
        - cancelRequested
        - error
        - createdAt
        - updatedAt
        - draft
      properties:
        jobId:
          format: uuid
          type: string
        status:
          $ref: "#/components/schemas/JobStatus"
        progress:
          minimum: 0
          maximum: 100
          type: integer
        cancelRequested:
          type: boolean
        error:
          anyOf:
            - type: object
              patternProperties:
                ^(.*)$: {}
            - type: "null"
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
        draft:
          description: 反推成功后的草稿摘要；未产出时为 null。
          anyOf:
            - $ref: "#/components/schemas/SuiteForgeDraftSummary"
            - type: "null"
    SuiteForgeResult:
      type: object
      required:
        - jobId
        - status
        - suite
        - createdAt
      properties:
        jobId:
          format: uuid
          type: string
        status:
          type: string
          enum:
            - DRAFT
            - COMMITTED
        suite:
          $ref: "#/components/schemas/EcomSuiteFile"
        suiteId:
          anyOf:
            - type: string
            - type: "null"
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
    TestProviderConnectionResult:
      type: object
      required:
        - ok
        - providerId
        - modelId
        - kind
        - latencyMs
        - models
        - modelAvailable
      properties:
        ok:
          type: boolean
        providerId:
          format: uuid
          type: string
        modelId:
          type: string
        kind:
          type: string
        latencyMs:
          type: number
        models:
          anyOf:
            - type: array
              items:
                type: string
            - type: "null"
        modelAvailable:
          anyOf:
            - type: boolean
            - type: "null"
    TestProviderInput:
      type: object
      required:
        - modelId
      properties:
        modelId:
          minLength: 1
          type: string
        kind:
          description: segmentation probes the declared segmentation API with zero cost.
          type: string
          enum:
            - reasoning
            - image
            - segmentation
    UpdateAssetInput:
      type: object
      properties:
        role:
          $ref: "#/components/schemas/AssetRole"
        kind:
          $ref: "#/components/schemas/UserAssetKind"
    UpdateEditSessionMemoryInput:
      type: object
      required:
        - summary
        - constraints
      properties:
        outputId:
          format: uuid
          type: string
        summary:
          type: string
        constraints:
          type: array
          items:
            type: string
    UploadAssetInput:
      type: object
      required:
        - file
      properties:
        file:
          format: binary
          type: string
        role:
          $ref: "#/components/schemas/AssetRole"
        kind:
          $ref: "#/components/schemas/UserAssetKind"
    UploadEditReferenceAssetInput:
      type: object
      required:
        - file
        - purpose
      properties:
        file:
          format: binary
          type: string
        purpose:
          $ref: "#/components/schemas/ReferencePurpose"