Text to 3D

To generate a 3D mesh from text, you must first create a preview task, which can then be optimized into a 3D mesh. This is done using a "TextTo3dTask" object.

Versions

Subnet

Generated in a centralized way through Bittensor. Results can vary in quality. To use this model version, specify subnet-v1 in the version parameter.

Premium

The latest and best. Supports additional features such as PBR textures. To use this model version, specify premium-v1 in the version parameter.

The Text to 3D Task object

Properties

Name
id
Type
string
Description
Unique identifier for the task.
Name
kind
Type
string
Description
The task kind. Can be either preview or optimize.
Name
status
Type
string
Description
The task status. Can be either queued, in_progress, succeeded or failed.
Name
seed
Type
integer
Description
The seed used to create the task.
Name
prompt
Type
string
Description
The text prompt used when creating the task.
Name
negativePrompt
Type
string
Description
The negative text prompt uesd when creating the task.
Name
urls
Type
object
Description
An object containing links to the assets that have been created.
- Name
  albedo
  Type
  string
  Description
  Path to the albedo texture .png file.
- Name
  obj
  Type
  string
  Description
  Path to the .obj 3D model file.
- Name
  thumbnail
  Type
  string
  Description
  Path to the .png preview image for the 3D model.
Name
creditsUsed
Type
integer
Description
The amount of credits used by creating this task.
Name
finishedAt
Type
timestamp
Description
Timestamp of when the task finished processing. Will be null if the task is not yet processed.
Name
createdAt
Type
timestamp
Description
Timestamp of when the task was created.

POST/v1/text-to-3d

Create a preview task

This endpoint allows you to create a preview task. When using the premium-v1 version, this creates an optimized task and there is no need to optimize it after it is done.

Required attributes

Name
prompt
Type
string
Description
Positive text prompt that describes what the outpush mesh should look like.

Optional attributes

Name
seed
Type
integer
Description
When you use the same prompt and seed, you will generate the same result. If null or omitted, the server chooses a random seed.
Name
negativePrompt
Type
string
Description
Negative text that the AI model should avoid when creating the mesh.
Name
version
Type
string
Description
Model version, either subnet-v1 or premium-v1.
Name
faceLimit
Type
integer
Description
Constrain the output to a maximum number of faces. If unspecified the AI model will choose the optimal amount.
Name
pbr
Type
boolean
Description
Generate PBR textures for the model.

Request

POST

/v1/text-to-3d

curl --request POST \
    --url https://api.goneural.ai/v1/text-to-3d \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
        "prompt": "string",
        "seed": 42
    }'

Response

  {
      "id": "7ea86276-8857-4284-938e-3b19c96519a8",
      "kind": "preview",
      "status": "queued",
      "seed": 42,
      "prompt": "string",
      "negativePrompt": null,
      "urls": {},
      "creditsUsed": 0,
      "finishedAt": null,
      "createdAt": "2024-07-20T18:06:31+00:00"
  }

POST/v1/text-to-3d/:task/optimize

Optimize a task

Deprecated This endpoint is not necessary when using the subnet-v1 and premium-v1 model versions.

This endpoint allows you to optimize a preview task, which will create a high quality 3D mesh.

Path parameters

Name
task
Type
uuid
Description
The id of the preview task you want to optimize.

Request

POST

/v1/text-to-3d/:task/optimize

curl --request POST \
    --url https://api.goneural.ai/v1/text-to-3d/c7908b81-10f6-45bf-9639-501c69043c07/optimize \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer Dk6cNsCTy5PG1elL8F0xrmwNTExdVC87rnHAn6QVa8d8c5b0' \
    --header 'Content-Type: application/json' \
    --data '{}'

Response

  {
      "id": "c7908b81-10f6-45bf-9639-501c69043c07",
      "kind": "optimize",
      "status": "succeeded",
      "seed": 17340321,
      "prompt": "string",
      "negativePrompt": null,
      "urls": {
        "thumbnail": "string",
        "obj": "string",
        "albedo": "string"
      },
      "creditsUsed": 0,
      "finishedAt": "2024-07-20T18:10:12+00:00",
      "createdAt": "2024-07-20T18:09:23+00:00"
  }

GET/v1/text-to-3d/:task

Retrieve a task

This endpoint allows you to check the status of a task.

Path parameters

Name
task
Type
uuid
Description
The ID of the task you are checking.

Request

GET

/v1/text-to-3d/:id

curl --request GET \
    --url https://api.goneural.ai/v1/text-to-3d/c7908b81-10f6-45bf-9639-501c69043c07 \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <token>'

Response

{
    "id": "c7908b81-10f6-45bf-9639-501c69043c07",
    "kind": "preview",
    "status": "succeeded",
    "seed": 0,
    "prompt": "string",
    "negativePrompt": null,
    "urls": {
        "thumbnail": "string",
        "obj": "string",
        "albedo": "string"
    },
    "creditsUsed": 0,
    "finishedAt": "2024-07-20T18:10:12+00:00",
    "createdAt": "2024-07-20T18:09:23+00:00"
}