MCP

MCP 服务器

使用现有 API Key，将 Sukidata 连接到支持 MCP 的客户端。

远程 MCP 地址https://mcp.sukidata.com/mcp

传输方式Streamable HTTP

身份验证Bearer API Key

访问凭证现有 Sukidata API Key

快速开始

连接你的客户端

在客户端的 MCP 设置中添加远程服务器：

1
获取 API Key
使用已有密钥，或在控制台创建，并妥善保存。
2
添加远程服务器
将 MCP 地址设为 https://mcp.sukidata.com/mcp，并通过 Authorization 请求头发送 API Key。
3
重新加载客户端
确认客户端的工具列表中出现 Sukidata。

通用远程 MCP 配置示例

{
  "mcpServers": {
    "sukidata": {
      "url": "https://mcp.sukidata.com/mcp",
      "headers": {
        "Authorization": "Bearer $SUKIDATA_API_KEY"
      }
    }
  }
}

不同客户端使用的配置文件名和环境变量语法可能不同，但都需要填写上面的服务器地址和 Bearer 请求头。

工具

Web Data 工具

使用返回的搜索 ID 调用 get_result，即可继续查询尚未完成的搜索，无需创建新请求。

google_search

Google 搜索

可能消耗积分

根据关键词和目标市场返回一页结构化 Google 搜索结果。

query搜索关键词。必填

location可读的搜索位置名称。可选

google_domainGoogle 域名，例如 google.co.jp。google.com

country_code language_code

国家或地区与界面语言。us · en

device search_type

设备类型与 Google 结果类型。desktop · web

safe_search fresh

安全搜索与结果复用选项。false

start wait_for_completion

结果偏移量与短暂等待选项。0 · true

twitter_user_timeline

Twitter 用户时间线

可能消耗积分

返回一个 Twitter 账号发布的公开内容。账号标识只能选择一种。

username用户名，可带或不带 @。二选一

user_idTwitter 数字用户 ID。二选一

max_results每页最多返回 1–100 条帖子。20

cursor上一页返回的不透明游标。可选

wait_for_completion短暂等待完整结果。true

get_result

获取已有结果

不产生新扣费

将 product 设为 serp 或 twitter，search_id 设为搜索工具返回的 ID。

图片

生成与编辑图片

图片生成通常需要 30 秒到两分钟。提交一次后，使用返回的 task_id 获取结果。

generate_image

生成图片

使用 AI Balance

必填 model、prompt 和 idempotency_key，默认生成一张图片。可选 images 用于提供参考图。

generate_image 参数

{
  "model": "gpt-image-2.5",
  "prompt": "A blue ceramic cup on a white background",
  "idempotency_key": "cup-example-1",
  "size": "1254x1254",
  "quality": "high"
}

edit_image

编辑图片

使用 AI Balance

接受相同参数，并要求提供 images：包含 1–16 张 PNG、JPEG 或 WebP 参考图的数组。每项可以是公共 HTTPS URL 或 Base64 data URL，也可以复用之前生成的图片 URL。

可选 mask 接受 PNG 蒙版 URL 或 data URL，尺寸应与第一张参考图一致，透明区域表示需要编辑的部分。单张图片不超过 20 MiB，包含蒙版的总大小不超过 32 MiB，具体数量还受模型限制。

上传本地图片

使用远程连接时，由客户端读取本地文件并发送 Base64 data URL。以下示例使用已连接的 MCP 客户端；JPEG 和 WebP 分别使用 image/jpeg 和 image/webp。

远程 MCP · 上传本地文件

import { readFile } from "node:fs/promises";

const image = await readFile("./photo.png");
await client.callTool({
  name: "edit_image",
  arguments: {
    model: "gpt-image-2.5",
    prompt: "Replace the background with a snowy mountain",
    idempotency_key: "upload-edit-example-1",
    images: ["data:image/png;base64," + image.toString("base64")]
  }
});

需要蒙版时，读取 PNG 文件并将其 data URL 传入 mask。重试同一次提交时，请保持文件内容、参数和 idempotency_key 不变。

图片参数

modelgpt-image-2.5 或 gpt-image-2，均支持以下参数。必填

idempotency_key每次计划生成使用一个唯一 key：1–128 个不含空格的可打印 ASCII 字符。提交中断后重试，必须复用原 key 和完整参数。必填

sizeauto 或 WIDTHxHEIGHT，详见图片尺寸。模型默认值

quality可选 auto、low、medium、high。模型默认值

n输出图片数量，生成和编辑每次均支持 1–4 张。1

output_formatpng、jpeg 或 webp。png

backgroundauto、opaque 或 transparent，透明背景需要 PNG 或 WebP。可选

output_compression0–100，用于 JPEG 和 WebP，不应用于 PNG。可选

moderationauto 或 low。可选

user你的终端用户标识，最多 256 个字符。可选

get_image_task

获取图片任务

不产生新扣费

必填 task_id。可选 wait_seconds 范围为 0–20，默认 20；结果就绪后会提前返回。设为 0 时只查询一次，不等待生成完成。

get_image_task 参数

{
  "task_id": "img_example",
  "wait_seconds": 20
}

返回 generating（生成中）、completed（已完成）或 failed（失败）。仍在生成时，使用相同 ID 再次调用此工具。也可以查询通过 API 或 Playground 创建的任务。

API 中处于 queued、processing 或 unknown 状态的任务，在此统一返回 generating。

完成后的 images 包含公共 URL、宽高、格式、字节数和 url_expires_at，实际输出参数和 usage 在可用时返回。链接自发布起可用 31 天，持有 URL 的人均可打开图片，请在到期前保存。

tools/call 结果的 content 同时包含 URL 资源链接与 ImageContent（type: "image"）。每个图片块紧跟对应链接，以 Base64 返回原始图片字节，不缩放图片或修改元数据。兼容的客户端可以直接展示或识别图片；远程 HTTP 与本地 stdio 返回相同格式。

tools/call · content

[
  { "type": "text", "text": "Image generation completed. 1 image(s)." },
  {
    "type": "resource_link",
    "uri": "https://files.sukidata.com/ai/images/example-token/img_example_0.png",
    "name": "image-1.png",
    "mimeType": "image/png"
  },
  {
    "type": "image",
    "mimeType": "image/png",
    "data": "<base64 image bytes>"
  }
]

内嵌图片在 Base64 编码前每张最多 5 MiB、合计最多 6 MiB。查询任务后，读图可能额外耗时最多 8 秒。超出大小限制或读取失败时，仍保留 URL，并在 content 中说明，不改变任务状态或费用。

等待超时不会取消生成。提交中断后，有任务 ID 就查询该任务；没有 ID 则使用相同的 idempotency_key 和原参数重试。查询出错不表示生成失败。

响应

结果与计费

工具通过 content 返回文字摘要，通过 structuredContent 返回结构化数据。Web Data 结果包含以下字段，搜索响应位于 data 中。

ok工具调用是否成功，搜索可能仍在进行。

search_id用于继续查询处理中的结果。

status搜索状态：Queued、Processing、Success 或 Error。

credits_used搜索结束后实际扣除的积分。

cache_hit工作区是否复用了已有结果。

request_id用于问题排查的请求标识。

Web Data Credits 与 AI Balance

Google 搜索和 Twitter 使用 Credits，实际消耗查看 credits_used。图片工具使用美元计价的 AI Balance，结果中的 billing.status 和 billing.charged_amount 表示计费状态与金额；尚未确认的金额为 null，不代表零费用。查询已有任务不产生新扣费。

计费说明

问题排查

连接时，HTTP 401 表示 Bearer 密钥缺失或格式无效；429 表示请求过于频繁。请检查连接配置，或等待后重试。

工具执行出错时返回 isError: true，具体原因查看 structuredContent.error 中的 code 和 message。

auth_failed 或 scope_forbidden：检查密钥状态和产品权限。
insufficient_credits 或 insufficient_ai_balance：为对应余额充值。
rate_limited：等待后重试相同操作。
submission_unconfirmed：查询已返回的任务 ID；没有 ID 时，使用原参数和 idempotency_key 重试。
image_status_unavailable 或 service_unavailable：如果已返回 ID，继续查询该任务；图片生成可能仍在进行。

连接时遇到问题？请发送邮件至 support@sukidata.com。