Getting Started with Sortium API

Sortium API is a RESTful based API that allows you to generate AI powered textures for 3d models.

Authentication

To use Sortium AI you first need a user account, which enable you to send requests through our API and access our application at app.sortium.com.

You can go to our authentication page and create a new Sortium account using your email or social network.

API Key

Once you have a user account, you can go to the API Key page and create a new API Key. Or revoke an existing one at the same page.

Check our detailed guide to learn how to create a new API Key.

API Documentation

Our API documentation is available in our docs page.

Usage

Generating a texture

Once you have an API Key, you can use it to generate a texture by sending a POST request to the /v1/texture endpoint.

curl --request POST \
  --url https://api.sortium.com/v1/texture \
  --header 'Accept: application/json' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: YOUR_API_KEY' \
  --form file=@Ukulele_01_1k.glb \
  --form export_format=gltf-embedded \
  --form 'texture_config={
	"prompt": "japanese wave painting texture",
	"negative_prompt": "3D, volumetric, shadows, reflections",
	"use_negative_prompt": true,
	"reference_image": "https://wallpaperaccess.com/full/34436.jpg",
	"reference_image_strength": 0.5,
	"style_prompt": "base",
	"supportive_prompt": "fine art ukulele",
	"conditioning_strength": 1.0
}' \
  --form select_all=true

This is set to target all materials inside the 3d model, you can change this behavior by setting the parameter select_all to false and changing the value of the parameter texture_config to be an array of texture configuration, containing the name of the material to be targeted.

Example:

curl --request POST \
  --url https://api.sortium.com/v1/texture \
  --header 'Accept: application/json' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: YOUR_API_KEY' \
  --form file=@Ukulele_01_1k.glb \
  --form export_format=gltf-embedded \
  --form 'texture_config={
  "list": [
    {
      "prompt": "japanese wave painting texture",
      "negative_prompt": "3D, volumetric, shadows, reflections",
      "use_negative_prompt": true,
      "material_name": "Ukulele_01",
			"reference_image": "https://wallpaperaccess.com/full/34436.jpg",
			"reference_image_strength": 1.0,
			"style_prompt": "base",
			"supportive_prompt": "ukulele",
			"conditioning_strength": 1.0,
      "strength": 0.7
    }
  ]
}' \
  --form select_all=false

This request returns a request ID that you can use later to check the processing status into our queue.

{
	"id": "980bccd2-fea6-46e8-b0a1-74a575ddd454",
	"created_at": "2023-11-24T14:42:02.914Z",
	"updated_at": "2023-11-24T14:42:03.115Z",
	"config": {
		"list": [
			{
				"enable_default_pipeline": false,
				"model": null,
				"prompt": "japanese wave painting texture",
				"tiling": null,
				"negative_prompt": "3D, volumetric, shadows, reflections",
				"use_negative_prompt": true,
				"steps": null,
				"cfg_scale": null,
				"sampler": null,
				"seed": 4043584,
				"use_random_seed": false,
				"material": null,
				"width": 768,
				"height": 768,
				"material_name": "Ukulele_01",
				"control_nets": null,
				"reference_image": "61ec29d5",
				"reference_image_strength": 1.0,
				"style_prompt": "base",
				"supportive_prompt": "ukulele",
				"conditioning_strength": 1.0,
        "strength": 0.7
			}
		]
	}
}

Now, using the ID we got as result of the first call, we can send a request to our verification endpoint to check the process status:

curl -X GET "https://api.sortium.com/v1/texture/980bccd2-fea6-46e8-b0a1-74a575ddd454" \
 -H "accept: application/json"\
 -H "x-api-key: YOUR_API_KEY"

This request returns the status of the process, which can be PROCESSING, ERROR , DONE or FINALIZED.

{
  "request_id": "e649a418-8417-4ea6-864e-d04ff0c57d78",
  "created_at": "2023-08-14T21:23:55.577089+00:00",
  "updated_at": "2023-08-14T21:23:56.835609+00:00",
  "status": "PROCESSING",
  "assets": []
}

This is an example of a successful task with the status FINALIZED:

{
	"request_id": "9c1041ae-2a59-4109-a3af-b50bde267723",
	"created_at": "2023-12-06T12:21:22.909Z",
	"updated_at": "2023-12-06T12:22:07.511Z",
	"status": "FINALIZED",
	"assets": {
		"id": "4f192daf-c2b3-48de-9e4b-7c0750a6c254",
		"assetHash": "none",
		"assetUrl": "https://uploads.sortium.com/9c1041ae-2a59-4109-a3af-b50bde267723.gltf",
		"extraInfo": {
			"preview_url": "https://images.sortium.com/9c1041ae-2a59-4109-a3af-b50bde267723_1080p.webp",
			"preview_png_url": null,
			"pending_preview": false,
			"config": [
				{
					"enable_default_pipeline": false,
					"model": null,
					"prompt": "japanese wave painting texture",
					"tiling": null,
					"negative_prompt": "3D, volumetric, shadows, reflections",
					"use_negative_prompt": true,
					"steps": null,
					"cfg_scale": null,
					"sampler": null,
					"seed": 4043584,
					"use_random_seed": false,
					"material": null,
					"width": 768,
					"height": 768,
					"material_name": "Ukulele_01",
					"control_nets": null,
					"reference_image": "b80126fe",
					"reference_image_strength": 0.5,
					"style_prompt": "base",
					"supportive_prompt": "fine art ukulele",
					"conditioning_strength": 1.0
				}
			]
		},
		"timeToComplete": 18,
		"__typename": null
	},
	"origin": "1f5a269c-5010-4815-96b0-2ab8ba4fa005"
}

The response object contains a URL to download the asset from our CDN, and another pointing to a preview image to be displayed into UI tools, we also returns the configuration object used to generate the textures.

INFO: A process get's the status FINALIZED after a user verify it's result, until them the process has the status DONE