3D

Crear modelo 3D

Crea una tarea de generación de modelo 3D

POST
/v1/3d/generations

Usa GET /v1/models?recommended_for=3d para obtener los modelos 3D actuales.

Genera modelos 3D a partir de texto o imágenes. Esta es una API asíncrona. Las respuestas de creación devuelven una identidad de tarea. Realiza sondeos (polling) a GET /v1/tasks/{id} con ella para consultar el estado.

La operación es text-to-3d o image-to-3d. Puedes omitir operation: las solicitudes solo con prompt se resuelven como text-to-3d, y las solicitudes con image o image_url se resuelven como image-to-3d. Si envías operation, debe coincidir con las entradas: image-to-3d necesita una imagen y text-to-3d no admite ninguna. El valor heredado 3d-generation devuelve 400 unsupported_operation. Cada modelo admite solo algunas operaciones; consulta GET /v1/models/{model}.

Cuerpo de la solicitud

Antes de enviar campos opcionales, consulta GET /v1/models/{model} para ver los parámetros aceptados por el modelo. El ejemplo utiliza únicamente model y prompt.

modelstringpredeterminado: tripo-h3.1

Modelo que se va a utilizar, por ejemplo tripo-h3.1 o tripo-p1.0. Consulta GET /v1/models?recommended_for=3d antes de depender de un tipo de entrada o formato de salida específico.

operationstring

text-to-3d o image-to-3d. Opcional; se infiere a partir de las entradas cuando se omite.

promptstringobligatorio

Descripción en texto del modelo 3D a generar, de hasta 2000 caracteres. Los modelos pueden establecer un límite más corto; consulta sus detalles. Las solicitudes de imagen a 3D también necesitan un prompt en los modelos actuales; sin él, la solicitud devuelve 400 prompt is required.

imagestring

Imagen codificada en Base64 para la generación de imagen a 3D.

image_urlstring

URL pública de una imagen para la generación de imagen a 3D.

formatstring

Formato de salida; la compatibilidad y los valores permitidos dependen del modelo seleccionado.

qualitystring

Ajuste de calidad; la compatibilidad y los valores permitidos dependen del modelo seleccionado.

stylestring

Preajuste de estilo para el modelo.

seedinteger

Semilla de tipo entero, cuando sea compatible con el modelo seleccionado.

userstring

Un identificador único para el usuario final. Envíalo solo cuando el modelo seleccionado lo acepte.

Algunos modelos también enumeran n, negative_prompt y output_format (un alias de format). Envíelos solo cuando los detalles del modelo los incluyan.

Respuesta

idstring

ID de la tarea para consultar el estado mediante polling.

task_idstring

Alias del identificador de la tarea asíncrona cuando lo devuelve el adaptador.

poll_urlstring

URL de estado para esta tarea. Realiza polling a GET /v1/tasks/{id} con id.

statusstring

Estado de la tarea: pending, processing, completed o failed.

createdinteger

Marca de tiempo Unix de la creación de la tarea.

Solicitud

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"
  }'

Respuesta

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

Autorización

BearerAuth
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Encabezados

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.

Valores permitidos

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

Clave opcional que hace que una solicitud de creación sea segura para reintentar. Envíe un nuevo valor único, como un UUID, para cada tarea. Un reintento con la misma clave y el mismo cuerpo devuelve el resultado de la solicitud de creación original, generalmente la tarea original, y no crea, envía ni cobra una segunda tarea. Un cuerpo diferente con una clave que ya fue aceptada se rechaza con 409. Se ignora una clave de más de 255 caracteres y la solicitud no tendrá protección de idempotencia. Consulte Reintente de forma segura con una clave de idempotencia.

Longitud1 <= length <= 255

Cuerpo de la solicitud

application/json

Respuesta

application/json

application/json

application/json

application/json

application/json

application/json