3D
创建 3D 模型
根据文字或图片生成 3D 模型
用文字或图片创建 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。
tripo-h3.1要使用的模型,例如 tripo-h3.1 或 tripo-p1.0。发送图片或指定输出格式前,请通过 GET /v1/models?recommended_for=3d 查看模型详情。
text-to-3d 或 image-to-3d。可选;省略时根据输入推断。
要生成的 3D 模型的文本描述,最多 2000 个字符;模型可以设置更短的上限,见模型详情。对当前模型,图生 3D 请求也要带 prompt,否则返回 400 prompt is required。
用于图像转 3D 生成的 Base64 编码图像。
用于图像转 3D 生成的公开图像 URL。
输出格式;是否支持及允许值取决于所选模型。
质量设置;是否支持及允许值取决于所选模型。
模型的风格预设。
整数种子,仅在所选模型支持时使用。
终端用户的唯一标识符。仅在所选模型接受时发送。
部分模型还列出 n、negative_prompt 和 output_format(format 的别名)。只有模型详情列出时才发送。
响应
用于查询状态的任务 ID。
返回时与 id 对应的同一异步任务标识。
任务的状态地址(如有)。用 id 调用 GET /v1/tasks/{id} 查询。
任务状态:pending、processing、completed 或 failed。
任务创建的 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"
}'响应
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"created": 1706000000,
"model": "tripo-h3.1"
}授权
BearerAuth API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。
位置: header
请求头
单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。
可选值
- "auto"
- "verified"
- "official"
可选键,用于确保创建请求可安全重试。请为每个任务发送一个新的唯一值(如 UUID)。使用相同键和相同请求体的重试将返回原始创建请求的结果(通常是原始任务),而不会创建、分发或扣除第二个任务。若使用已接受的键但请求体不同,则会返回 409 错误。超过 255 个字符的键将被忽略,此时该请求不具备幂等性保护。请参阅 安全地使用幂等键进行重试。
1 <= length <= 255请求体
application/json
响应
application/json
application/json
application/json
application/json
application/json
application/json