TokenLab

3D

3D 모델 생성

3D 모델 생성 작업을 생성합니다

POST
/v1/3d/generations

현재 3D 모델 목록을 확인하려면 GET /v1/models?recommended_for=3d를 사용하세요.

텍스트 또는 이미지로부터 3D 모델을 생성합니다. 이는 비동기 API입니다. 생성 요청 응답으로 작업 식별자가 반환됩니다. 해당 식별자로 GET /v1/tasks/{id}를 폴링하여 상태를 확인하세요.

작업(operation)은 text-to-3d 또는 image-to-3d입니다. operation을 생략할 수 있습니다. 프롬프트만 포함된 요청은 text-to-3d로 처리되며, image 또는 image_url이 포함된 요청은 image-to-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자까지 가능합니다. 모델에 따라 더 짧은 제한이 적용될 수 있으니 세부 정보를 참조하세요. 현재 모델에서는 Image-to-3D 요청에도 prompt가 필요하며, 누락 시 요청에서 400 prompt is required가 반환됩니다.

imagestring

Image-to-3D 생성을 위한 Base64 인코딩된 이미지입니다.

image_urlstring

Image-to-3D 생성을 위한 공개 이미지 URL입니다.

formatstring

출력 형식입니다. 지원 여부 및 허용되는 값은 선택한 모델에 따라 다릅니다.

qualitystring

품질 설정입니다. 지원 여부 및 허용되는 값은 선택한 모델에 따라 다릅니다.

stylestring

모델의 스타일 프리셋입니다.

seedinteger

정수 시드(seed) 값으로, 선택한 모델이 지원하는 경우 사용됩니다.

userstring

최종 사용자의 고유 식별자입니다. 선택한 모델이 지원하는 경우에만 전송하세요.

일부 모델은 n, negative_prompt, output_format(format의 별칭)도 나열합니다. 모델 세부 정보에 해당 항목이 나열된 경우에만 전송하십시오.

응답

idstring

상태를 폴링하기 위한 작업 ID입니다.

task_idstring

어댑터에서 반환될 때의 비동기 작업 식별자 별칭입니다.

poll_urlstring

이 작업의 상태 확인 URL입니다. 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 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: 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