Seed3D v1

Seed3D v1 API 参考

通过单张图片 URL 生成 GLB 3D 资产。公开 API 使用用户 API 密钥创建异步任务，并返回标准化状态和输出 URL。

API v1https://seed3d-ai.org/v180 credits

快速开始

curl -X POST 'https://seed3d-ai.org/v1/generate' \
  -H 'Authorization: Bearer YOUR_ZA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "https://example.com/product.png",
    "prompt": "clean topology, neutral studio lighting",
    "subdivision_level": "medium"
  }'

身份认证

每个公开 API 请求都需要在 Authorization header 中携带用户 API 密钥。

请在控制台创建或复制密钥： API 密钥

Authorization: Bearer YOUR_ZA_API_KEY

定价

图像转 3D 生成

任务被接受时扣减积分。上游提交失败会由后端自动退回。

80 credits

API 端点

提交一张图片 URL 和可选生成提示，响应会立即返回 task_id。

`image` required string	公网 HTTP 或 HTTPS 图片 URL。推荐 JPG、PNG 和 WebP 输入。
`prompt` optional string	可选文本提示，用于描述表面、材质、几何或资产用途。最多 2000 字符。
`subdivision_level` optional string	网格细节提示。支持 low、medium、high，或数字别名 0、1、2。default: provider default
`public` optional boolean	生成结果是否可被下游功能作为公开内容处理。default: false
`callback_url` optional string	可选公网 webhook URL，会随任务保存。不接受 localhost。

请求示例

{
  "image": "https://example.com/product.png",
  "prompt": "clean topology, neutral studio lighting",
  "subdivision_level": "medium",
  "public": false,
  "callback_url": "https://example.com/webhooks/seed3d"
}

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n105abc123s3d",
    "status": "IN_PROGRESS",
    "consumed_credits": 80
  }
}

轮询直到状态为 SUCCESS 或 FAILED。成功任务的 response 是输出 URL 数组。

task_id

required string

POST /v1/generate 返回的任务 ID。

请求示例

curl -X GET 'https://seed3d-ai.org/v1/status?task_id=n105abc123s3d' \
  -H 'Authorization: Bearer YOUR_ZA_API_KEY'

响应

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "n105abc123s3d",
    "status": "SUCCESS",
    "consumed_credits": 80,
    "request": {
      "image": "https://example.com/product.png",
      "prompt": "clean topology, neutral studio lighting",
      "subdivision_level": "medium"
    },
    "response": [
      "https://cdn.example.com/seed3d-output.glb"
    ],
    "error_message": null
  }
}

查询 Authorization header 中 API 密钥创建的最近任务。

`page` optional number	分页页码。default: 1
`limit` optional number	每页数量，由后端限制上限。default: 20
`task_id` optional string	可选的精确任务 ID 过滤。

请求示例

curl -X GET 'https://seed3d-ai.org/v1/list?page=1&limit=20' \
  -H 'Authorization: Bearer YOUR_ZA_API_KEY'

控制台工具

开发接入时，可使用控制台创建密钥并查看日志。

打开 API 密钥打开 API 日志

错误代码

HTTP	原因
400	请求参数缺失或无效。
401	Authorization bearer token 缺失或无效。
402	API 密钥账户积分不足。
403	请求的 API key 与 bearer token 不一致。
404	任务 ID 不存在。
405	该路由不允许当前 HTTP 方法。
500	服务端或上游提供商错误，请稍后重试或联系支持。