import requests

response = requests.post(
    f"https://api.stability.ai/v2beta/3d/stable-point-aware-3d",
    headers={
        "authorization": f"Bearer sk-MYAPIKEY",
    },
    files={
        "image": open("./cat-statue.png", "rb")
    },
    data={},
)

if response.status_code == 200:
    with open("./3d-cat-statue.glb", 'wb') as file:
        file.write(response.content)
else:
    raise Exception(str(response.json()))

"<string>"

{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "name": "bad_request",
  "errors": [
    "some-field: is required"
  ]
}

{
  "id": "ed14db44362126aab3cbd25cca51ffe3",
  "name": "content_moderation",
  "errors": [
    "Your request was flagged by our content moderation system, as a result your request was denied and you were not charged."
  ]
}

{
  "id": "4212a4b66fbe1cedca4bf2133d35dca5",
  "name": "payload_too_large",
  "errors": [
    "body: payloads cannot be larger than 10MiB in size"
  ]
}

{
  "id": "rate_limit_exceeded",
  "name": "rate_limit_exceeded",
  "errors": [
    "You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."
  ]
}

{
  "id": "2a1b2d4eafe2bc6ab4cd4d5c6133f513",
  "name": "internal_error",
  "errors": [
    "An unexpected server error has occurred, please try again later."
  ]
}

Stable Point Aware 3D

Stable Point Aware 3D (SPAR3D) can make real-time edits and create the complete structure of a 3D object from a single image in a few seconds. SPAR3D combines the strengths of point-cloud diffusion (probabilistic) and mesh regression (deterministic) to have improved details on the unseen back regions in the input image.

Compared to our previous model Stable Fast 3D, this new one allows editing of backside information using the point cloud representation and also leverages a larger Diffusion model to generally improve the depth and backside predictions.

Read more about the model capabilities here.

This API is currently in preview. Please don’t hesitate to contact us with any questions.

Try it out

Grab your API key and head over to

How to use

Please invoke this endpoint with a POST request.

The headers of the request must include an API key in the authorization field. The body of the request must be multipart/form-data.

The body of the request should include:

image

The body may optionally include:

texture_resolution
foreground_ratio
remesh
target_type
target_count
guidance_scale
seed

Note: for more details about these parameters please see the request schema below.

Output

The output is a binary blob that includes a glTF asset, including JSON, buffers, and images. See the GLB File Format Specification for more details.

Credits

Flat rate of 4 credits per successful generation. You will not be charged for failed generations.

POST

v2beta

stable-point-aware-3d

import requests

response = requests.post(
    f"https://api.stability.ai/v2beta/3d/stable-point-aware-3d",
    headers={
        "authorization": f"Bearer sk-MYAPIKEY",
    },
    files={
        "image": open("./cat-statue.png", "rb")
    },
    data={},
)

if response.status_code == 200:
    with open("./3d-cat-statue.glb", 'wb') as file:
        file.write(response.content)
else:
    raise Exception(str(response.json()))

"<string>"

{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "name": "bad_request",
  "errors": [
    "some-field: is required"
  ]
}

{
  "id": "ed14db44362126aab3cbd25cca51ffe3",
  "name": "content_moderation",
  "errors": [
    "Your request was flagged by our content moderation system, as a result your request was denied and you were not charged."
  ]
}

{
  "id": "4212a4b66fbe1cedca4bf2133d35dca5",
  "name": "payload_too_large",
  "errors": [
    "body: payloads cannot be larger than 10MiB in size"
  ]
}

{
  "id": "rate_limit_exceeded",
  "name": "rate_limit_exceeded",
  "errors": [
    "You have exceeded the rate limit of 150 requests within a 10 second period, and have been timed out for 60 seconds."
  ]
}

{
  "id": "2a1b2d4eafe2bc6ab4cd4d5c6133f513",
  "name": "internal_error",
  "errors": [
    "An unexpected server error has occurred, please try again later."
  ]
}

Authorizations

authorization

string

header

required

Use your Stability API key to authentication requests to this App.

Headers

authorization

string

required

Your Stability API key, used to authenticate your requests. Although you may have multiple keys in your account, you should use the same key for all requests to this API.

Minimum string length: 1

content-type

string

required

The content type of the request body. Do not manually specify this header; your HTTP client library will automatically include the appropriate boundary parameter.

Minimum string length: 1

Example:

"multipart/form-data"

stability-client-id

string

The name of your application, used to help us communicate app-specific debugging or moderation issues to you.

Maximum string length: 256

Example:

"my-awesome-app"

stability-client-user-id

string

A unique identifier for your end user. Used to help us communicate user-specific debugging or moderation issues to you. Feel free to obfuscate this value to protect user privacy.

Maximum string length: 256

Example:

"DiscordUser#9999"

stability-client-version

string

The version of your application, used to help us communicate version-specific debugging or moderation issues to you.

Maximum string length: 256

Example:

"1.2.1"

Body

multipart/form-data

image

file

required

The image to generate a 3D model from.

Supported Formats:

jpeg
png
webp

Validation Rules:

Every side must be at least 64 pixels
Total pixel count must be between 4,096 and 4,194,304 pixels

texture_resolution

enum<string>

default:1024

Determines the resolution of the textures used for both the albedo (color) map and the normal map. The resolution is specified in pixels, and a higher value corresponds to a higher level of detail in the textures, allowing for more intricate and precise rendering of surfaces. However, increasing the resolution also results in larger asset sizes, which may impact loading times and performance. 1024 is a good default value and rarely requires changing.

Available options:

512,

1024,

2048

foreground_ratio

number

default:1.3

Controls the amount of padding around the object to be processed within the frame. This ratio determines the relative size of the object compared to the total frame size. A higher ratio means less padding and a larger object, while a lower ratio increases the padding, effectively reducing the object’s size within the frame. This can be useful when a long and narrow object, such as a car or bus, is viewed from the front (the narrow side). Here, lowering the foreground ratio might help prevent the generated 3D assets from appearing squished or distorted. The default value of 1.3 is good for most objects.

Required range: 1 <= x <= 2

remesh

enum<string>

default:none

Controls the remeshing algorithm used to generate the 3D model. The remeshing algorithm determines how the 3D model is constructed from the input image. The default value of "none" means that the model is generated without remeshing, which is suitable for most use cases. The "triangle" option generates a model with triangular faces, while the "quad" option generates a model with quadrilateral faces. The "quad" option is useful when the 3D model will be used in DCC tools such as Maya or Blender.

Available options:

none,

triangle,

quad

target_type

enum<string>

default:none

If set to vertex or face, the result will have approximately target_count many vertices or faces in the simplified mesh, respectively.

Available options:

none,

vertex,

face

target_count

number

default:1000

This sets the target vertex or face count defined by target_type. Selecting extremely low counts reduces the quality of the mesh severely and values of 1,000 - 10,000 are recommended.

Required range: 100 <= x <= 20000

guidance_scale

number

default:3

This sets the guidance scaling of the point diffusion module. Lower values produce less detail and higher can introduce artifacts. The default of 3 produces best results.

Required range: 1 <= x <= 10

seed

number

default:0

A specific value that is used to guide the 'randomness' of the generation. (Omit this parameter or pass 0 to use a random seed.)

Required range: 0 <= x <= 4294967294

Response

Generation was successful.

The bytes of the generated 3D model.