API 文档

通过 HTTP API 调用 Lovstudio 的创意工具。当前支持手工川风格复刻 — 输入一张人像照片，返回线稿风格的头像。设计上对 Agent 工具调用友好。

Tool Plugin Protocol：lovstudio.tool.v1

Lovstudio 工具现在以插件 manifest 注册。插件可以复用账号登录、API Key、credits 扣费、OpenAPI、 llm.txt 发现、站内 ranking/filter 和详情页元信息。

Auth

支持匿名、登录态与 Bearer API Key。API 插件使用 sk_live_*。

Credits

manifest 声明扣费单位；上游失败后按插件策略自动退款。

Protocol

声明 inputs、outputs、endpoints、runtime 和部署方式，供 UI 与 LLM 读取。

manifest.ts

{
  id: "my-research-tool",
  i18nKey: "myResearchTool",
  version: "0.1.0",
  publisher: "community",
  category: "ai",
  runtime: "api",
  status: "beta",
  iconName: "Sparkles",
  keywords: ["research", "agent"],
  tags: ["api", "credits"],
  capabilities: ["web-research", "structured-output"],
  createdAt: "2026-05-15",
  source: {
    type: "community",
    repo: "https://github.com/you/my-research-tool"
  },
  infra: {
    auth: "apiKey",
    credits: "metered",
    protocol: "lovstudio.tool.v1",
    deploy: "external",
    scopes: ["auth:api-key", "credits:spend", "protocol:http"]
  },
  billing: {
    model: "credits",
    creditsPerRun: 10,
    unit: "run",
    refund: "automatic"
  },
  protocol: {
    inputs: ["query"],
    outputs: ["markdown", "citations"],
    endpoints: [{
      method: "POST",
      path: "/api/v1/my-research-tool",
      operationId: "runMyResearchTool",
      auth: "apiKey",
      credits: 10
    }]
  }
}

插件发现

catalog

curl "https://cs-magic.cn/api/v1/tool-plugins?category=ai&runtime=api&billing=credits&sort=rank"

公开 JSON： /api/v1/tool-plugins。完整开发文档见仓库内 docs/tool-plugin-protocol.md。

发布与复制同款

登录开发者可在 /tools 上传 manifest，系统会写入社区插件目录；其他用户刷新后即可看到并使用。每张工具卡片也提供复制同款 manifest，用于快速 fork 一个相同输入/输出结构的插件。

1. 获取 API Key

登录后前往 /account/api-keys 生成 Key。Key 形如 sk_live_...，仅在生成时显示一次，请立即保存。

Key 与你的账户余额绑定 — 每次调用扣 70 credits。

2. 调用示例

curl

curl -X POST https://cs-magic.cn/api/v1/style-remix \
  -H "Authorization: Bearer sk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "style": "shougongchuan"
  }'

Node.js

const res = await fetch("https://cs-magic.cn/api/v1/style-remix", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOVSTUDIO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    image_url: "https://example.com/photo.jpg",
  }),
})
const { image_base64, mime_type } = await res.json()
require("fs").writeFileSync(
  "out.png",
  Buffer.from(image_base64, "base64"),
)

Python

import os, base64, requests

resp = requests.post(
    "https://cs-magic.cn/api/v1/style-remix",
    headers={"Authorization": f"Bearer {os.environ['LOVSTUDIO_API_KEY']}"},
    json={"image_url": "https://example.com/photo.jpg"},
    timeout=120,
)
data = resp.json()
with open("out.png", "wb") as f:
    f.write(base64.b64decode(data["image_base64"]))

3. 端点参考：POST /api/v1/style-remix

请求体（二选一）

image_base64: 原始 base64（可含data:image/...;base64, 前缀），最大 10MB
image_url: 公网可访问的 https URL
mime_type（可选）: 默认 image/jpeg
style（可选）: 仅支持 shougongchuan

成功响应

{
  "image_base64": "iVBORw0KGgoAAA...",
  "mime_type": "image/png",
  "style": "shougongchuan",
  "credits_spent": 70,
  "upstream_text": null
}

延迟与超时

同步返回，典型 10–30 秒。建议客户端 timeout 设为 120s 以上。

4. 错误码

error	HTTP	含义
missing_authorization	401	未带 Authorization 头
invalid_api_key	401	Key 无效或已撤销
invalid_json	400	请求体不是合法 JSON
missing_image	422	未提供 image_base64 或 image_url
invalid_image	422	图片解析失败 / 太大 / 不是图片
invalid_style	422	style 字段不在受支持值列表中
insufficient_credits	402	余额不足 — 前往 /pricing 充值
upstream_unreachable	502	上游模型网络异常 — 已自动退款
upstream_error	502	上游模型返回错误 — 已自动退款
no_image	502	上游未返回图片 — 已自动退款

所有错误响应都带 error（机器可读）和 message（人类可读）字段。请用 error 做分支。

5. Agent 工具描述

把以下 schema 直接给 Claude / OpenAI / LangChain 作为 tool definition：

{
  "name": "remix_portrait_in_shougongchuan_style",
  "description": "Redraw a portrait photo in the 手工川 cute black-line-on-orange style. Returns base64 PNG. Costs 70 credits.",
  "input_schema": {
    "type": "object",
    "properties": {
      "image_url": { "type": "string", "format": "uri" },
      "image_base64": { "type": "string" },
      "mime_type": { "type": "string" }
    },
    "oneOf": [
      { "required": ["image_url"] },
      { "required": ["image_base64"] }
    ]
  }
}

机读 OpenAPI 3.1 spec： /api/v1/openapi