3D

创建 3D 模型

根据文字或图片生成 3D 模型

POST
/v1/3d/generations

用文字或图片创建 3D 模型。创建成功后会返回任务 ID,调用 GET /v1/tasks/{id} 查询进度和结果。

操作为 text-to-3d 或 image-to-3d。可以不传 operation:只有 prompt 时为文生 3D,带有 image 或 image_url 时为图生 3D。如果传了 operation,必须与输入一致:image-to-3d 需要图片,text-to-3d 不带图片。旧值 3d-generation 会返回 400 unsupported_operation。每个模型只支持部分操作,请查看 GET /v1/models/{model}。

请求体

发送可选字段前,请通过 GET /v1/models/{model} 查看该模型接受的参数。示例只发送 model 和 prompt。

modelstring默认值: tripo-h3.1

要使用的模型,例如 tripo-h3.1 或 tripo-p1.0。发送图片或指定输出格式前,请通过 GET /v1/models?recommended_for=3d 查看模型详情。

operationstring

text-to-3d 或 image-to-3d。可选;省略时根据输入推断。

promptstring必填

要生成的 3D 模型的文本描述,最多 2000 个字符;模型可以设置更短的上限,见模型详情。对当前模型,图生 3D 请求也要带 prompt,否则返回 400 prompt is required。

imagestring

用于图像转 3D 生成的 Base64 编码图像。

image_urlstring

用于图像转 3D 生成的公开图像 URL。

formatstring

输出格式;是否支持及允许值取决于所选模型。

qualitystring

质量设置;是否支持及允许值取决于所选模型。

stylestring

模型的风格预设。

seedinteger

整数种子,仅在所选模型支持时使用。

userstring

终端用户的唯一标识符。仅在所选模型接受时发送。

部分模型还列出 n、negative_prompt 和 output_format(format 的别名)。只有模型详情列出时才发送。

响应

idstring

用于查询状态的任务 ID。

task_idstring

返回时与 id 对应的同一异步任务标识。

poll_urlstring

任务的状态地址(如有)。用 id 调用 GET /v1/tasks/{id} 查询。

statusstring

任务状态:pending、processing、completed 或 failed。

createdinteger

任务创建的 Unix 时间戳。

请求

curl -X POST "https://api.tokenlab.sh/v1/3d/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo-h3.1",
    "prompt": "A detailed medieval castle with towers"
  }'

响应

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "tripo-h3.1"
}

授权

BearerAuth
AuthorizationBearer <token>

API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

请求头

X-TokenLab-Delivery-Policy?string

单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。

可选值

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

可选键,用于确保创建请求可安全重试。请为每个任务发送一个新的唯一值(如 UUID)。使用相同键和相同请求体的重试将返回原始创建请求的结果(通常是原始任务),而不会创建、分发或扣除第二个任务。若使用已接受的键但请求体不同,则会返回 409 错误。超过 255 个字符的键将被忽略,此时该请求不具备幂等性保护。请参阅 安全地使用幂等键进行重试。

长度1 <= length <= 255

请求体

application/json

响应

application/json

application/json

application/json

application/json

application/json

application/json