API开发者文档
将 AI 设计能力
集成到您的产品中
RESTful API，简单接入，强大能力
API 概览
NeuralCraft API 允许开发者将 AI 电商图片生成能力集成到自己的产品、工作流或平台中。所有 API 请求均通过 HTTPS 进行，返回 JSON 格式的响应。
Base URL：https://api.neuralcraft.cn/v1
当前 API 版本为 v1。我们承诺在发布新版本前至少提前 6 个月通知，并在 12 个月的过渡期内保持旧版本的兼容性。
支持的功能
| 功能 | API 端点 | 说明 |
|---|---|---|
| 商品图生成 | /generate/product | 上传产品图，生成完整详情页图组 |
| 风格迁移 | /generate/style | 参考指定风格，生成统一风格的图片 |
| 批量处理 | /batch | 一次性提交多个生成任务 |
| 任务查询 | /tasks/{id} | 查询异步任务的执行状态和结果 |
认证方式
所有 API 请求需要在 HTTP Header 中携带 API Key 进行认证。您可以在控制台的「开发者设置」中生成和管理 API Key。
Authorization: Bearer nc_your_api_key_here
安全提示：请勿将 API Key 暴露在客户端代码中。建议在服务端调用 API，或使用环境变量存储密钥。
获取 API Key
1. 登录 NeuralCraft 控制台
2. 进入「设置 → 开发者设置」
3. 点击「生成 API Key」
4. 复制并妥善保存您的密钥
图片生成
上传产品图片，AI 自动分析并生成完整的电商详情页图组。支持全品类商品、自定义场景和多种输出风格。
POST/generate/product
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| image | File | 必填 | 产品图片文件，支持 JPG/PNG/WebP，最大 10MB |
| category | String | 必填 | 产品类别：3c / beauty / clothing / food / home / other |
| style | String | 可选 | 风格模板 ID，默认使用智能推荐 |
| scene | String | 可选 | 场景描述，如"简约白底""户外自然光" |
| count | Integer | 可选 | 生成图片数量，1-6，默认 6 |
| size | String | 可选 | 输出尺寸：1080x1080 / 1200x1600 / 1920x1080 / 4k，默认 1200x1600 |
| callback_url | String | 可选 | 异步回调地址，任务完成后 POST 通知 |
请求示例
curl -X POST "https://api.neuralcraft.cn/v1/generate/product" \\
-H "Authorization: Bearer nc_your_api_key" \\
-F "image=@product.jpg" \\
-F "category=3c" \\
-F "scene=科技简约风" \\
-F "count=6" \\
-F "size=1200x1600"
响应示例
{
"code": 0,
"message": "success",
"data": {
"task_id": "task_20240820123456_abc123",
"status": "processing",
"estimated_time": 30,
"created_at": "2024-08-20T12:34:56Z"
}
}
风格迁移
上传参考图片和产品图片，AI 将参考图的设计风格（配色、排版、光影）应用到产品上，保持品牌视觉一致性。
POST/generate/style
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| product_image | File | 必填 | 产品图片 |
| reference_image | File | 必填 | 参考风格图片 |
| preserve_text | Boolean | 可选 | 是否保留参考图中的文案结构，默认 true |
| match_ratio | Float | 可选 | 风格匹配强度 0.1-1.0，默认 0.7 |
请求示例
curl -X POST "https://api.neuralcraft.cn/v1/generate/style" \\
-H "Authorization: Bearer nc_your_api_key" \\
-F "product_image=@my_product.jpg" \\
-F "reference_image=@reference_design.jpg" \\
-F "match_ratio=0.8"
批量处理
一次性提交多个生成任务，适合大规模商品上架场景。批量任务会进入队列依次执行，您可以通过任务 ID 查询整体进度。
POST/batch
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| tasks | Array | 必填 | 任务数组，每个元素包含独立的生成参数 |
| parallel | Boolean | 可选 | 是否并行执行，默认 false（队列执行） |
| priority | Integer | 可选 | 优先级 1-5，Enterprise 用户可用，默认 3 |
请求示例
curl -X POST "https://api.neuralcraft.cn/v1/batch" \\
-H "Authorization: Bearer nc_your_api_key" \\
-H "Content-Type: application/json" \\
-d '{
"tasks": [
{"image_url": "https://example.com/p1.jpg", "category": "3c", "style": "tech"},
{"image_url": "https://example.com/p2.jpg", "category": "beauty", "style": "luxury"}
],
"parallel": false
}'
任务状态查询
所有生成任务均为异步执行。提交后获得 task_id，通过此接口查询任务执行状态和获取结果。
GET/tasks/{task_id}
响应示例 — 处理中
{
"code": 0,
"data": {
"task_id": "task_20240820123456_abc123",
"status": "processing",
"progress": 65,
"stage": "生成详情图中"
}
}
响应示例 — 已完成
{
"code": 0,
"data": {
"task_id": "task_20240820123456_abc123",
"status": "completed",
"images": [
{"type": "main", "url": "https://cdn.neuralcraft.cn/.../main.jpg", "size": "1200x1600"},
{"type": "scene", "url": "https://cdn.neuralcraft.cn/.../scene.jpg", "size": "1200x1600"},
{"type": "detail", "url": "https://cdn.neuralcraft.cn/.../detail.jpg", "size": "1200x1600"}
],
"expires_at": "2024-08-27T12:34:56Z"
}
}
错误码
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 0 | 成功 | — |
| 1001 | API Key 无效或已过期 | 检查 Authorization Header，或在控制台重新生成 |
| 1002 | 额度不足 | 升级方案或购买额外额度 |
| 2001 | 图片格式不支持 | 使用 JPG、PNG 或 WebP 格式 |
| 2002 | 图片大小超过限制 | 压缩图片至 10MB 以内 |
| 2003 | 图片内容检测失败 | 确保上传的是清晰的产品图片 |
| 3001 | 任务队列已满 | 稍后再试，或升级 Enterprise 获取优先队列 |
| 3002 | 生成超时 | 重新提交任务，复杂图片可能需要更长时间 |
| 4001 | 参数错误 | 对照文档检查请求参数 |
| 5001 | 服务器内部错误 | 请联系技术支持 |
速率限制
为保障服务稳定性，API 调用实行速率限制。限制按账户维度计算，与您的订阅方案相关。
| 方案 | QPS 限制 | 并发任务 | 日调用上限 |
|---|---|---|---|
| Starter | 2 | 1 | 500 |
| Pro | 10 | 3 | 5,000 |
| Enterprise | 50 | 10 | 无限制 |
超过速率限制时，API 返回 HTTP 429 状态码，响应头中包含 X-RateLimit-Reset 表示限制重置的 Unix 时间戳。
SDK
我们提供官方 SDK，简化 API 接入流程。
# Python
pip install neuralcraft
# Node.js
npm install @neuralcraft/sdk
# Java
<dependency>
<groupId>cn.neuralcraft</groupId>
<artifactId>sdk</artifactId>
<version>1.0.0</version>
</dependency>
SDK 源码和更多示例可在 GitHub 获取。如需技术支持，请联系 enterprise@neuralcraft.cn。