Text To Texture API

Text To Texture API is a feature that allows you to integrate Meshy's Text to Texture capabilities into your own application. In this section, you'll find all the information you need to get started with this API.


POST/openapi/v1/text-to-texture

Create a Text to Texture Task

This endpoint allows you to create a new Text to Texture task. Refer to The Text to Texture Task Object to see which properties are included with Text to Texture task object.

Parameters

Required attributes

  • Name
    model_url
    Type
    string
    Description

    Downloadable URL to the 3D model for Meshy to texture. Currently, we support .fbx / .obj / .stl / .gltf / .glb models..

  • Name
    object_prompt
    Type
    string
    Description

    Describe what kind of object the 3D model is.

  • Name
    style_prompt
    Type
    string
    Description

    Describe your desired style of the object.

Optional attributes

  • Name
    enable_original_uv
    Type
    boolean
    Description

    Use the original UV of the model instead of generating new UVs. If the model has no original UV, the quality of the output might not be as good. Default to true if not specified.

  • Name
    enable_pbr
    Type
    boolean
    Description

    Generate PBR Maps (metallic, roughness, normal) in addition to the base color. Default to true if not specified.

  • Name
    resolution
    Type
    string
    Description

    Specify the resolution of generated textures. Available values:

    • 1024
    • 2048
    • 4096
  • Name
    negative_prompt
    Type
    string
    Description

    Describe what the texture should not look like.

  • Name
    art_style
    Type
    string
    Description

    Describe your desired art style of the object. Default to realistic if not specified. Available values:

    • realistic: Realistic style
    • fake-3d-cartoon: 2.5D Cartoon style
    • japanese-anime: Japanese Anime style
    • cartoon-line-art: Cartoon Line Art style
    • realistic-hand-drawn: Realistic Hand-drawn style
    • fake-3d-hand-drawn: 2.5D Hand-drawn style
    • oriental-comic-ink: Oriental Comic Ink style

Returns

The result property of the response contains the task id of the newly created Text to Texture task.

Request

POST
/openapi/v1/text-to-texture
curl https://api.meshy.ai/openapi/v1/text-to-texture \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "https://cdn.meshy.ai/model/example_model_2.glb",
    "object_prompt": "a monster mask",
    "style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
    "enable_original_uv": true,
    "enable_pbr": true,
    "resolution": "1024",
    "negative_prompt": "low quality, low resolution, low poly, ugly",
    "art_style": "realistic"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/text-to-texture/:id

Retrieve a Text to Texture Task

This endpoint allows you to retrieve a Text to Texture task given a valid task id. Refer to The Text to Texture Task Object to see which properties are included with Text to Texture task object.

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the Text to Texture task to retrieve.

Returns

The response contains the Text to Texture task object. Check The Text to Texture Task Object section for details.

Request

GET
/openapi/v1/text-to-texture/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v1/text-to-texture/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "object_prompt": "a monster mask",
  "style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
  "art_style": "realistic",
  "negative_prompt": "low quality, low resolution, low poly, ugly",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  }
}

The Text to Texture Task Object

The Text to Texture Task object is a work unit that Meshy keeps track of to generate a 3D texture from a text input. The model has the following properties:

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the task. While we use a k-sortable UUID for task ids as the implementation detail, you should not make any assumptions about the format of the id.

  • Name
    model_url
    Type
    string
    Description

    Downloadable URL to the textured 3D model file generated by Meshy.

  • Name
    model_urls
    Type
    object
    Description

    Downloadable URL to the textured 3D model file generated by Meshy.

    • Name
      glb
      Type
      string
      Description

      Downloadable URL to the GLB file.

    • Name
      fbx
      Type
      string
      Description

      Downloadable URL to the FBX file.

    • Name
      usdz
      Type
      string
      Description

      Downloadable URL to the USDZ file.

  • Name
    object_prompt
    Type
    string
    Description

    This is unmodified object_prompt that was used to create the task.

  • Name
    style_prompt
    Type
    string
    Description

    This is unmodified style_prompt that was used to create the task.

  • Name
    art_style
    Type
    string
    Description

    This is unmodified art_style that was used to create the task.

  • Name
    negative_prompt
    Type
    string
    Description

    This is unmodified negative_prompt that was used to create the task.

  • Name
    thumbnail_url
    Type
    string
    Description

    Downloadable URL to the thumbnail image of the model file.

  • Name
    progress
    Type
    integer
    Description

    Progress of the task. If the task is not started yet, this property will be 0. Once the task has succeeded, this will become 100.

  • Name
    started_at
    Type
    timestamp
    Description

    Timestamp of when the task was started, in miliseconds. If the task is not started yet, this property will be 0.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the task was created, in miliseconds.

  • Name
    expires_at
    Type
    timestamp
    Description

    Timestamp of when the task result expires, in miliseconds.

  • Name
    finished_at
    Type
    timestamp
    Description

    Timestamp of when the task was finished, in miliseconds. If the task is not finished yet, this property will be 0.

  • Name
    status
    Type
    string
    Description

    Status of the task. Possible values are one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, EXPIRED.

  • Name
    texture_urls
    Type
    array
    Description

    An array of texture URL objects that are generated from the task. Normally this only contains one texture URL object. Each texture URL has the following properties:

    • Name
      base_color
      Type
      string
      Description

      Downloadable URL to the base color map image.

    • Name
      metallic
      Type
      string
      Description

      Downloadable URL to the metallic map image.

    • Name
      normal
      Type
      string
      Description

      Downloadable URL to the normal map image.

    • Name
      roughness
      Type
      string
      Description

      Downloadable URL to the roughness map image.

  • Name
    preceding_tasks
    Type
    integer
    Description

    The count of preceding tasks.

  • Name
    task_error
    Type
    object
    Description

    Error object that contains the error message if the task failed. The message property should be empty if the task succeeded.

    • Name
      message
      Type
      string
      Description

      Detailed error message.

Example Text to Texture Task Model

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
  },
  "object_prompt": "a monster mask",
  "style_prompt": "red fangs, Samurai outfit that fused with japanese batik style",
  "art_style": "realistic",
  "negative_prompt": "low quality, low resolution, low poly, ugly",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 1,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  }
}