3D
Create 3D Model
Creates a 3D model generation task
Use GET /v1/models?recommended_for=3d to get current 3D models.
Generate 3D models from text or images. This is an asynchronous API. Create responses return a task identity. Poll GET /v1/tasks/{id} with it for status.
The operation is text-to-3d or image-to-3d. You can leave operation out: prompt-only requests resolve to text-to-3d, and requests with image or image_url resolve to image-to-3d. If you send operation, it must match the inputs: image-to-3d needs an image, and text-to-3d takes none. The legacy 3d-generation value returns 400 unsupported_operation. Each model supports only some operations; check GET /v1/models/{model}.
Request Body
Before sending optional fields, check GET /v1/models/{model} for the model’s accepted parameters. The example uses only model and prompt.
tripo-h3.1Model to use, for example tripo-h3.1 or tripo-p1.0. Query GET /v1/models?recommended_for=3d before relying on a specific input type or output format.
text-to-3d or image-to-3d. Optional; inferred from the inputs when omitted.
Text description of the 3D model to generate, up to 2000 characters. Models can set a shorter limit; see their details. Image-to-3D requests also need a prompt for the current models; without one the request returns 400 prompt is required.
Base64-encoded image for image-to-3D generation.
Public URL of an image for image-to-3D generation.
Output format; support and allowed values depend on the selected model.
Quality setting; support and allowed values depend on the selected model.
Style preset for the model.
Integer seed, when supported by the selected model.
A unique identifier for the end-user. Send it only when the selected model accepts it.
Some models also list n, negative_prompt, and output_format (an alias of format). Send them only when the model's details list them.
Response
Task ID for polling status.
Async task identifier alias when returned by the adapter.
Status URL for this task. Poll GET /v1/tasks/{id} with id.
Task status: pending, processing, completed, or failed.
Unix timestamp of task creation.
Request
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"
}Authorization
BearerAuth API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Headers
Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.
Value in
- "auto"
- "verified"
- "official"
Optional key that makes a create request safe to retry. Send a new unique value, such as a UUID, for each task. A retry with the same key and the same body returns the result of the original create request, usually the original task, and does not create, dispatch, or charge a second task. A different body with a key that was already accepted is rejected with 409. A key longer than 255 characters is ignored, and the request then has no idempotency protection. See Retry safely with an idempotency key.
1 <= length <= 255Request Body
application/json
Response
application/json
application/json
application/json
application/json
application/json
application/json