civitai-orchestration

Civitai 编排

通过 Civitai Orchestration API 查询工作流、查看任务详情并获取生成结果。

快速开始

# Query workflows for a specific user
node .claude/skills/civitai-orchestration/civitai-client.js user 12345

# Get a specific workflow by ID
node .claude/skills/civitai-orchestration/civitai-client.js workflow <workflowId>

# Get job details with scan results (hive_csam_score, etc.)
node .claude/skills/civitai-orchestration/civitai-client.js job <jobId>

# Get step details from a workflow
node .claude/skills/civitai-orchestration/civitai-client.js step <workflowId> <stepName>

# Download result images/videos from a workflow
node .claude/skills/civitai-orchestration/civitai-client.js results <workflowId>

搜索与筛选

按用户 ID

# Get workflows for user 12345
node civitai-client.js user 12345

# With options
node civitai-client.js user 12345 --take=5 --excludeFailed

按工作流 ID

# Direct lookup by workflow ID
node civitai-client.js workflow 0-019be44b-181e-7a7e-ab1b-b58dc7610dca

按日期范围

注意： 日期筛选功能可能受 API 访问级别限制。

# Workflows from the last 7 days
node civitai-client.js workflows --from=2024-01-15 --to=2024-01-22

# Workflows from a specific day
node civitai-client.js workflows --from=2024-01-20 --to=2024-01-20

# Dates are assumed to be UTC. Add Z suffix for explicit UTC:
node civitai-client.js workflows --from=2024-01-20T06:00:00Z --to=2024-01-20T12:00:00Z

替代方法： 使用 --oldest 从最早的工作流开始获取，然后分页：

# Get oldest workflows first
node civitai-client.js workflows --oldest --take=50

按标签

创建工作流时会设置标签。常见的标签模式：

# Filter by a specific tag
node civitai-client.js workflows --tag=user:12345

# Note: Multiple tags can be specified (AND logic)
node civitai-client.js workflows --tag=project:myproject --tag=type:image

按元数据搜索

--query 选项会搜索工作流元数据：

# Search metadata for a string
node civitai-client.js workflows --query="portrait"

按状态

API 支持排除失败的工作流，但不支持按特定状态筛选：

# Exclude failed/canceled workflows (get only succeeded/processing)
node civitai-client.js workflows --excludeFailed

# Include all statuses (default behavior)
node civitai-client.js workflows

注意： 若要查找特定状态的工作流，请获取工作流后在客户端进行筛选；也可以在创建工作流时使用元数据或标签，以便更好地筛选。

分页

# Get 50 results
node civitai-client.js workflows --take=50

# Get next page using cursor from previous response
node civitai-client.js workflows --take=20 --cursor=<nextCursor>

组合筛选条件

# Successful workflows for a specific tag, excluding failures
node civitai-client.js workflows \
  --tag=user:12345 \
  --excludeFailed \
  --take=50

# Get workflows with metadata search
node civitai-client.js workflows \
  --query="portrait" \
  --excludeFailed \
  --take=20

命令参考

test

测试 API 连接并验证凭据。

node civitai-client.js test

user

根据特定用户的 Civitai 用户 ID 查询其工作流。

node civitai-client.js user <userId> [options]

选项：

选项	描述
--take=<n>	结果数量（受 API 限制，最多为 10）
--tag=<tag>	按标签筛选
--query=<text>	搜索工作流元数据
--excludeFailed	排除失败/已取消的工作流
--oldest	按从最早到最新的顺序排序

workflows

列出并搜索工作流，可选用筛选条件。

node civitai-client.js workflows [options]

选项：

选项	描述
--tag=<tag>	按标签筛选（可指定多个）
--query=<text>	搜索工作流元数据
--excludeFailed	排除失败/已取消的工作流
--oldest	按从最早到最新的顺序排序
--take=<n>	结果数量（默认值：20）
--cursor=<cursor>	分页游标
--from=<date>	开始日期（支持可能受限）
--to=<date>	结束日期（支持可能受限）

workflow

获取特定工作流的详情。

node civitai-client.js workflow <workflowId> [--wait]

选项：

选项	描述
--wait	等待/轮询直至完成（带超时）

job

获取特定任务的详情，包括事件上下文中的扫描结果。

这适用于调查内容审核结果——lastEvent.context 包含扫描分数，例如 hive_csam_score 和 hive_vlm_summary。

node civitai-client.js job <jobId> [--raw]

选项：

选项	描述
--raw	输出原始 JSON，而非格式化摘要

输出示例：

Job Summary:
  ID: 58de87d7-d594-4d71-ae43-dd8fc1bcbd23
  Type: TextToImageV2
  Workflow ID: 8484131-20260121222126332

Prompt Classification: sexual, young, scan

Results (2 blob(s)):
  - JNFDW54JNTATNW42HACYCWSQP0.jpeg (available: true)

Last Event:
  Type: Succeeded
  Provider: ValdiAI

Event Context (scan results, metrics):
  ** hive_csam_score: 0.00 %, 0.00 %
  ** hive_vlm_summary: X, No_Child

step

获取工作流中特定步骤的详情。

node civitai-client.js step <workflowId> <stepName>

results

下载或查看工作流的结果（图片/视频）。

node civitai-client.js results <workflowId> [--download] [--dir=<path>]

选项：

选项	描述
--download	下载结果文件
--dir=<path>	下载目录（默认值：./civitai-downloads）

blob

根据 ID 获取 blob（图片/视频），可选处理 NSFW 内容。

node civitai-client.js blob <blobId> [--download] [--nsfw]

环境变量

存储在 .claude/skills/civitai-orchestration/.env 中：

CIVITAI_API_TOKEN=your_bearer_token
CIVITAI_API_URL=https://orchestration.civitai.com

API 参考

工作流查询参数

工作流端点支持以下查询参数：

• tags - 用于筛选的标签数组
• query - 搜索工作流元数据
• fromDate / toDate - 日期范围（ISO 8601）- 支持可能受限
• cursor - 分页游标
• take - 结果数量（默认值：100）
• excludeFailed - 排除失败/已过期/已取消的工作流（布尔值）
• ascending - 按从最早到最新的顺序排序（布尔值）

工作流状态

状态	描述
preparing	正在准备工作流
scheduled	已安排执行
processing	正在运行
succeeded	已成功完成
failed	执行失败
canceled	已取消
expired	已超时
deleted	已删除

步骤类型（配方）

你可能会遇到的图像/视频生成步骤：

• textToImage - 文本生成图像
• imageGen - 通用图像生成
• videoGen - 视频生成
• videoEnhancement - 视频放大/增强
• videoFrameExtraction - 从视频中提取帧
• videoUpscaler - 视频放大
• videoInterpolation - 帧插值
• convertImage - 转换图像格式
• comfy - 执行 ComfyUI 工作流
• preprocessImage - 对图像执行 ControlNet 预处理（输出为 blob，即图像）
• preprocessVideo - 对视频执行 ControlNet 预处理（输出为 blob，即 VideoBlob）
• aceStepAudio - 音频生成；blob 为 AudioBlob，或在封面图模式下为 VideoBlob
• miniMaxMusic3 - 音乐生成

示例

查询用户最近生成的图像

# Get user 12345's recent workflows
node civitai-client.js user 12345

# Exclude failed jobs
node civitai-client.js user 12345 --excludeFailed

获取工作流并查看结果

# Get workflow details
node civitai-client.js workflow abc123-def456

# View/download results
node civitai-client.js results abc123-def456 --download --dir=./my-images

分页浏览工作流

# First page
node civitai-client.js workflows --take=10

# Next page (use cursor from previous response)
node civitai-client.js workflows --take=10 --cursor=<nextCursor>

错误处理

错误代码	含义
401	令牌无效或已过期——请检查 CIVITAI_API_TOKEN
404	未找到工作流/作业
429	请求频率受限——请稍后重试
422	参数无效

输出

user 命令会显示工作流摘要，包括：

• 工作流 ID、状态、时间戳
• 步骤类型（textToImage、videoGen、comfy 等）
• 文本生成图像任务的提示词

如需原始 JSON 输出，请使用 workflow 命令：

node civitai-client.js workflow <workflowId>