TokenLab

3D

Create 3D Model

Creates a 3D model generation task

POST
/v1/3d/generations

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.

modelstringdefault: tripo-h3.1

Model 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.

operationstring

text-to-3d or image-to-3d. Optional; inferred from the inputs when omitted.

promptstringrequired

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.

imagestring

Base64-encoded image for image-to-3D generation.

image_urlstring

Public URL of an image for image-to-3D generation.

formatstring

Output format; support and allowed values depend on the selected model.

qualitystring

Quality setting; support and allowed values depend on the selected model.

stylestring

Style preset for the model.

seedinteger

Integer seed, when supported by the selected model.

userstring

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

idstring

Task ID for polling status.

task_idstring

Async task identifier alias when returned by the adapter.

poll_urlstring

Status URL for this task. Poll GET /v1/tasks/{id} with id.

statusstring

Task status: pending, processing, completed, or failed.

createdinteger

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

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

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Headers

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

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.

Length1 <= length <= 255

Request Body

application/json

Response

application/json

application/json

application/json

application/json

application/json

application/json