梭子蟹API 文档
用量
立即开始
Base URLhttps://suoxie.codes/v1

API 参考

图像生成与编辑

调用同步图像生成和编辑接口。

同步图像接口 ​

同步接口会保持 HTTP 连接直到图像生成或编辑完成，适合预计能在客户端超时前结束的任务。长耗时、批量或网络不稳定场景优先使用异步图像任务。

操作方法与路径请求格式
生成图像POST /v1/images/generationsJSON
编辑图像POST /v1/images/edits通常为 multipart/form-data

图像能力必须同时得到当前平台、分组和模型支持。先用 /v1/models 确认模型，再进行小尺寸单张测试。

最小生成请求 ​

bash
curl --fail-with-body https://suoxie.codes/v1/images/generations \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"<MODEL>","prompt":"A clean technical diagram","size":"1024x1024"}'

常用生成字段 ​

字段类型必填说明
modelstring是当前分组支持图像能力的模型 ID
promptstring是清晰描述目标主体、构图和约束
sizestring否可用尺寸由模型决定；示例值不代表所有模型均支持
ninteger否生成数量；支持范围与计费以当前模型为准

不要从其他服务的教程复制参数并假设本站模型支持。遇到 400 时先退回 model + prompt 的最小组合。

成功响应 ​

json
{
  "created": 1786464000,
  "data": [
    {
      "url": "https://storage.example/image.png"
    }
  ]
}

实际结果可能使用 URL 或模型支持的其他内容形式。URL 通常有访问期限，业务需要长期保存时应尽快下载到自己受控的存储，并遵守内容与隐私要求。

编辑请求 ​

编辑端点使用相同认证。文件上传通常使用 multipart 表单，不要手工添加 JSON Content-Type，让 cURL 自动生成 boundary：

bash
curl --fail-with-body https://suoxie.codes/v1/images/edits \
  -H "Authorization: Bearer <API_KEY>" \
  -F "model=<MODEL>" \
  -F "prompt=Replace the background with a clean studio wall" \
  -F "image=@./input.png"

文件字段、遮罩和格式支持随模型变化。第一次编辑使用小文件，不包含敏感图片，并以实际错误信息调整字段。

同步还是异步 ​

场景建议
单张、短任务、人工调试同步接口
生成时间可能超过客户端超时异步接口
需要在断线后继续查询异步接口
需要 Webhook 或取消当前异步合约不提供，调用方需自行设计业务层

常见错误 ​

403 通常表示分组未开放图像权限；404 可能是平台不支持 Images 或异步功能未启用；413 表示请求/文件过大；429 需要等待并检查额度；网关超时不一定代表上游没有执行，重试前先查看用量记录。

安全与费用 ​

图片提示、原图和结果可能包含敏感内容，不要写入公开日志。限制上传大小、并发和 Key 配额。不要对超时请求立即无限重试，否则可能产生重复图像和费用。

下一步 ​

长任务改用异步图像任务，完成后在 Key 用量核对模型、图片数量和费用。