Katechon Technology Custom Endpoints API

openapi: 3.2.0
info:
  title: Katechon Arc Custom Endpoints API
  description: Agent-powered AI video studio
  version: 1.0.0
tags:
- name: Custom Endpoints
paths:
  /api/v1/custom-endpoints/preview-request:
    post:
      tags:
      - Custom Endpoints
      summary: Preview Endpoint Request
      description: 渲染将要发出的请求，不外发。凭证打码、素材换成体积摘要、提交后才有的 id 保持占位符。
      operationId: preview_endpoint_request_api_v1_custom_endpoints_preview_request_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewResponse'
      security:
      - OAuth2PasswordBearer: []
  /api/v1/custom-endpoints/check-response:
    post:
      tags:
      - Custom Endpoints
      summary: Check Endpoint Response
      description: 用一份供应商真实响应验证取值路径与状态映射，不外发。零费用。
      operationId: check_endpoint_response_api_v1_custom_endpoints_check_response_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckResponseInput'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Check Endpoint Response Api V1 Custom Endpoints Check Response Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - OAuth2PasswordBearer: []
  /api/v1/custom-endpoints/trial-runs:
    post:
      tags:
      - Custom Endpoints
      summary: Start Trial Run
      description: '真实提交一次生成并轮询到终态，**会产生费用**。接口不设确认参数——明示计费归调用方。


        定义内联或 ``model_ref`` 二选一：后者按模型行解析端点与凭证，内置与自定义走同一资源、同一

        结果体、同一记账。每用户同时只允许一个。'
      operationId: start_trial_run_api_v1_custom_endpoints_trial_runs_post
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialRunResponse'
      security:
      - OAuth2PasswordBearer: []
  /api/v1/custom-endpoints/trial-runs/{run_id}:
    get:
      tags:
      - Custom Endpoints
      summary: Get Trial Run
      description: 读一次测试连接。运行中读内存、终态读盘；取消或被重启打断的 run 不留结果。
      operationId: get_trial_run_api_v1_custom_endpoints_trial_runs__run_id__get
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrialRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/custom-endpoints/trial-runs/{run_id}/cancel:
    post:
      tags:
      - Custom Endpoints
      summary: Cancel Trial Run
      description: 停本地轮询，记账按失败结算。远端由 backend 的取消路径自己叫停，停不下来时照跑、钱照花。
      operationId: cancel_trial_run_api_v1_custom_endpoints_trial_runs__run_id__cancel_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/custom-endpoints/trial-runs/{run_id}/artifact:
    get:
      tags:
      - Custom Endpoints
      summary: Get Trial Run Artifact
      description: 播放该测试连接生成的产物。
      operationId: get_trial_run_artifact_api_v1_custom_endpoints_trial_runs__run_id__artifact_get
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/custom-endpoints/comfyui/infer:
    post:
      tags:
      - Custom Endpoints
      summary: Infer Endpoint Bindings
      description: '推断一份 workflow 的节点绑定候选；带既有节点绑定时同时做重导入重匹配。


        服务端不留状态：结果不入库，客户端拿它渲染绑定编辑器，用户确认后经端点的创建或整份替换接口

        保存。``media_type`` 只在载荷是原始 workflow 时生效——端点定义自己带着这一项。'
      operationId: infer_endpoint_bindings_api_v1_custom_endpoints_comfyui_infer_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: media_type
        in: query
        required: false
        schema:
          enum:
          - image
          - video
          type: string
          default: video
          title: Media Type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InferResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/custom-endpoints:
    post:
      tags:
      - Custom Endpoints
      summary: Create Endpoint
      description: '创建（即导入）一条自定义调用端点。请求体是定义 JSON 原样，键由系统分配。


        请求体也可以是一份 ComfyUI 的原始 API workflow，此时服务端按 ``media_type`` 把它包成

        ComfyUI 端点定义——包装结果的节点绑定是空的，因此会被「提示词与产物必须绑定」挡下。'
      operationId: create_endpoint_api_v1_custom_endpoints_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: media_type
        in: query
        required: false
        schema:
          enum:
          - image
          - video
          type: string
          default: video
          title: Media Type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Body
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomEndpointResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Custom Endpoints
      summary: List Endpoints
      description: 列出全部自定义调用端点（含定义本体）。
      operationId: list_endpoints_api_v1_custom_endpoints_get
      security:
      - OAuth2PasswordBearer: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomEndpointListResponse'
  /api/v1/custom-endpoints/validate:
    post:
      tags:
      - Custom Endpoints
      summary: Validate Endpoint Definition
      description: '保存前的单段确认：形状分流 + 校验诊断 + 同作者同名的既有端点 + 提示回显 + 版本档位 + 应用版本门槛。服务端不留任何状态。


        ``exclude_id`` 供编辑既有端点时排除自身，否则它总会把自己报成重复。载荷是原始 API workflow

        时，回的每一项都算在包装结果上——客户端接着要带走的就是它。'
      operationId: validate_endpoint_definition_api_v1_custom_endpoints_validate_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: exclude_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Exclude Id
      - name: media_type
        in: query
        required: false
        schema:
          enum:
          - image
          - video
          type: string
          default: video
          title: Media Type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/custom-endpoints/{endpoint_id}:
    get:
      tags:
      - Custom Endpoints
      summary: Get Endpoint
      description: 读取单条端点。导出即取本响应的 ``definition`` 存成文件，服务端不参与下载。
      operationId: get_endpoint_api_v1_custom_endpoints__endpoint_id__get
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: integer
          title: Endpoint Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomEndpointResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Custom Endpoints
      summary: Update Endpoint
      description: 整份替换定义。原地更新：键与模型行挂接不变，新任务立即用新定义。
      operationId: update_endpoint_api_v1_custom_endpoints__endpoint_id__put
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: integer
          title: Endpoint Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomEndpointResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Custom Endpoints
      summary: Delete Endpoint
      description: '删除端点；被模型行引用时拒删并回引用清单。


        不级联删除引用它的模型行——模型行承载用户手工配置（定价、能力覆盖），级联会丢用户劳动；

        也不留悬空引用，那只会把错误推迟到生成时才爆。'
      operationId: delete_endpoint_api_v1_custom_endpoints__endpoint_id__delete
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: integer
          title: Endpoint Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SchemaVersionLevel:
      type: string
      enum:
      - direct
      - warning
      - confirm
      title: SchemaVersionLevel
      description: 文件 ``schema_version`` 相对当前版本的档位。
    DuplicateDescriptor:
      properties:
        id:
          type: integer
          title: Id
        key:
          type: string
          title: Key
        display_name:
          type: string
          title: Display Name
        version:
          type: string
          title: Version
        relation:
          $ref: '#/components/schemas/VersionRelation'
      type: object
      required:
      - id
      - key
      - display_name
      - version
      - relation
      title: DuplicateDescriptor
      description: 与待导入定义同作者同名（``meta.author`` + ``meta.name``）的既有端点。
    EndpointInstallationResponse:
      properties:
        source_key:
          type: string
          title: Source Key
        source_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Source Id
        source_display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Display Name
        source_enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Source Enabled
        slug:
          type: string
          title: Slug
        installed_version:
          type: string
          title: Installed Version
        installed_at:
          type: string
          title: Installed At
        state:
          type: string
          enum:
          - current
          - update_available
          - unavailable
          title: State
        modified:
          type: boolean
          title: Modified
      type: object
      required:
      - source_key
      - source_id
      - source_display_name
      - source_enabled
      - slug
      - installed_version
      - installed_at
      - state
      - modified
      title: EndpointInstallationResponse
    CustomEndpointListResponse:
      properties:
        endpoints:
          items:
            $ref: '#/components/schemas/CustomEndpointResponse'
          type: array
          title: Endpoints
      type: object
      required:
      - endpoints
      title: CustomEndpointListResponse
    PreviewedRequestResponse:
      properties:
        method:
          type: string
          title: Method
        url:
          type: string
          title: Url
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
        body:
          title: Body
      type: object
      required:
      - method
      - url
      - headers
      title: PreviewedRequestResponse
    SchemaVersionInfo:
      properties:
        file:
          anyOf:
          - type: string
          - type: 'null'
          title: File
        current:
          type: string
          title: Current
        level:
          $ref: '#/components/schemas/SchemaVersionLevel'
      type: object
      required:
      - file
      - current
      - level
      title: SchemaVersionInfo
      description: 文件版本与当前版本的比对结果。``level`` 只是提示信号，闸门始终是 schema 校验器。
    CustomEndpointResponse:
      properties:
        id:
          type: integer
          title: Id
        key:
          type: string
          title: Key
        display_name:
          type: string
          title: Display Name
        kind:
          type: string
          title: Kind
        schema_version:
          type: string
          title: Schema Version
        media_type:
          type: string
          title: Media Type
        definition:
          additionalProperties: true
          type: object
          title: Definition
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated At
        installation:
          anyOf:
          - $ref: '#/components/schemas/EndpointInstallationResponse'
          - type: 'null'
      type: object
      required:
      - id
      - key
      - display_name
      - kind
      - schema_version
      - media_type
      - definition
      title: CustomEndpointResponse
      description: 一条自定义调用端点。``definition`` 即导出内容，客户端直接存成文件。
    NotePayload:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      type: object
      required:
      - code
      - message
      title: NotePayload
      description: 一条提示。不拦保存，但有它用户才知道某个形态会怎么表现。
    VersionRelation:
      type: string
      enum:
      - newer
      - same
      - older
      title: VersionRelation
      description: 既有定义的 ``meta.version`` 相对导入文件的新旧关系。
    KeyInferencePayload:
      properties:
        state:
          type: string
          title: State
        candidates:
          items:
            $ref: '#/components/schemas/CandidatePayload'
          type: array
          title: Candidates
        notes:
          items:
            $ref: '#/components/schemas/NotePayload'
          type: array
          title: Notes
      type: object
      required:
      - state
      - candidates
      - notes
      title: KeyInferencePayload
      description: 一个语义键的推断结果。
    PreviewResponse:
      properties:
        submit:
          $ref: '#/components/schemas/PreviewedRequestResponse'
        poll:
          $ref: '#/components/schemas/PreviewedRequestResponse'
        result:
          anyOf:
          - $ref: '#/components/schemas/PreviewedRequestResponse'
          - type: 'null'
        conversions:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Conversions
      type: object
      required:
      - submit
      - poll
      title: PreviewResponse
      description: '渲染后的各节请求，外加「这份请求是怎么算出来的」。


        ``conversions`` 的形状由定义的 ``kind`` 决定：声明式端点的请求全部来自模板直填、没有可说明

        的换算，为 null；ComfyUI 端点给出尺寸 / 帧数 / 种子的换算与这次改图删掉的节点。'
    CandidatePayload:
      properties:
        target:
          additionalProperties: true
          type: object
          title: Target
        score:
          type: integer
          title: Score
        signals:
          items:
            $ref: '#/components/schemas/SignalPayload'
          type: array
          title: Signals
        selected:
          type: boolean
          title: Selected
        origin:
          type: string
          title: Origin
        depth:
          anyOf:
          - type: integer
          - type: 'null'
          title: Depth
      type: object
      required:
      - target
      - score
      - signals
      - selected
      - origin
      title: CandidatePayload
      description: 一条候选：可直接写进 ``bindings`` 的条目，加上它凭什么被选中。
    ImportShape:
      type: string
      enum:
      - endpoint_definition
      - comfyui_api_workflow
      - comfyui_ui_workflow
      title: ImportShape
      description: 一份导入载荷的形状。
    TrialRunResponse:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          title: Status
        provider:
          type: string
          title: Provider
        model:
          type: string
          title: Model
        created_at:
          type: number
          title: Created At
        finished_at:
          anyOf:
          - type: number
          - type: 'null'
          title: Finished At
        api_call_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Api Call Id
        provider_job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Job Id
        stages:
          additionalProperties:
            type: string
          type: object
          title: Stages
          default: {}
        request:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Request
        submit_response:
          title: Submit Response
        poll_responses:
          items: {}
          type: array
          title: Poll Responses
          default: []
        result_response:
          title: Result Response
        extractions:
          additionalProperties: true
          type: object
          title: Extractions
          default: {}
        video_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Video Url
        duration_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Seconds
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        error_action:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Action
        has_artifact:
          type: boolean
          title: Has Artifact
          default: false
      type: object
      required:
      - id
      - status
      - provider
      - model
      - created_at
      title: TrialRunResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ValidateResponse:
      properties:
        errors:
          items:
            additionalProperties:
              type: string
            type: object
          type: array
          title: Errors
        warnings:
          items:
            additionalProperties:
              type: string
            type: object
          type: array
          title: Warnings
        duplicates:
          items:
            $ref: '#/components/schemas/DuplicateDescriptor'
          type: array
          title: Duplicates
        hints:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Hints
        schema_version:
          $ref: '#/components/schemas/SchemaVersionInfo'
        min_app_version:
          anyOf:
          - $ref: '#/components/schemas/MinAppVersionInfo'
          - type: 'null'
        import_shape:
          $ref: '#/components/schemas/ImportShape'
        wrapped_definition:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Wrapped Definition
      type: object
      required:
      - errors
      - warnings
      - duplicates
      - schema_version
      - import_shape
      title: ValidateResponse
    InferResponse:
      properties:
        media_type:
          type: string
          title: Media Type
        savable:
          type: boolean
          title: Savable
        bindings:
          additionalProperties:
            $ref: '#/components/schemas/KeyInferencePayload'
          type: object
          title: Bindings
        notes:
          items:
            $ref: '#/components/schemas/NotePayload'
          type: array
          title: Notes
        import_shape:
          $ref: '#/components/schemas/ImportShape'
        wrapped_definition:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Wrapped Definition
      type: object
      required:
      - media_type
      - savable
      - bindings
      - notes
      - import_shape
      title: InferResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MinAppVersionInfo:
      properties:
        required:
          type: string
          title: Required
        current:
          type: string
          title: Current
        satisfied:
          type: boolean
          title: Satisfied
      type: object
      required:
      - required
      - current
      - satisfied
      title: MinAppVersionInfo
      description: '``meta.min_app_version`` 与当前应用版本的比对。不满足只是提示，不拦导入。'
    CheckResponseInput:
      properties:
        definition:
          title: Definition
        stage:
          type: string
          enum:
          - submit
          - poll
          - result
          title: Stage
        response_body:
          title: Response Body
      type: object
      required:
      - definition
      - stage
      title: CheckResponseInput
    SignalPayload:
      properties:
        signal:
          type: string
          title: Signal
        weight:
          type: integer
          title: Weight
        message:
          type: string
          title: Message
      type: object
      required:
      - signal
      - weight
      - message
      title: SignalPayload
      description: 一条命中的信号：稳定名、它贡献的分量、给用户看的说明。
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/v1/auth/token