Bell

You can now generate any object from text to 3D with Alpha3D AI Model Generator. Give it a try for free >>

Docs

API overview

Alpha3D API is designed to enable partner applications to access account data and assets directly from the Alpha3D application via HTTPS queries. With our API, partner applications can seamlessly retrieve data and 3D assets, and easily integrate them into their own applications.

To start using the Alpha3D API, please reach out to us via info@alpha3d.io to request access. We will work with you to enable API usage for your application and provide any necessary resources to ensure a smooth integration.

Currently, our API is offering four endpoints that partner applications can use to retrieve information from our system:

  1. Logging in
  2. Querying products
  3. Querying 3D models
  4. Generate 3D models

The log in endpoint is to enable partner application’s users to log in to their Alpha3D account, which is a prerequisite to retrieve 3D assets information from Alpha3D. The products endpoint should be used if users want to retrieve product information that has been accepted by the user in Alpha3D. Finally, the partner application can do a query to retrieve the 3D asset information together with the file(s).

Alpha3D provides the endpoints, while partner applications have the flexibility to develop their own business processes around these endpoints to best meet their specific needs. See the example process flow below:

When a user opens the Alpha3D integration in the partner application, then the partner application redirects to Alpha3D and displays the log in form to the user. The user has a choice to log in either using their credentials or using their Google account. When they choose to log in with their credentials, partner application makes a query to log the user in. If successful, then Alpha3D returns
a Bearer token which holds the user’s session information and user is redirected back to the partner application.

After that, the partner application can do another query to retrieve the user’s accepted products from Alpha3D. If there are any products that have a given 3D model file attached to them, then Alpha3D returns the product’s info and thumbnail which are then displayed to the user in the partner application.

User can then choose a product which 3D model file they want to retrieve and use in the partner application. When user has chosen the product, partner application will do a query to Alpha3D. When Alpha3D returns the 3D model, the partner application can display the 3D model and user can use the 3D asset in the partner application.

Changes/updates in Alpha3D API

If you need to make a request to our API, please feel free to contact us via info@alpha3d.io. We are always happy to hear from our partners and will carefully review each request. If possible, we will make updates or changes to our API to better meet your needs.

 

 

Authentication

All API calls made to Alpha3D need to be sent over secure HTTPS channel. To access the user’s assets and information, the API calls need to be authenticated with a unique and temporary bearer token that is assigned when user is logged in using the API on the partner application’s side. This token is used to validate if the query is authorized and the user has a valid session.

 

 

Requests

Each request consists of a URL and header parameters. Request can also consist of body parameters and authorization parameters.

The exact request URL format and parameters are described in the specific query description.

 

 

Responses

Each response contains the data from Alpha3D based on the given parameters. In case a query was not executed, the server returns an HTTPS error code together with the error description.

A response format for each query is described in the specific query description.

 

 

Logging in

Description

The goal of this service is to provide a query for partner applications to let users on their side log in to their account in Alpha3D.

 

Request

Method HTTP request Description
POST /alphaar/auth/oauth/token Logs the user in with the provided credentials.

 

Header parameters

Parameter Required? Description
grant_type Yes Possible values:

  • “password”
  • “authorization_code”
  • “refresh_token”
refresh_token No Bearer token’s refresh token.

Is valued only if header parameter grant_type = “refresh_token”

code No Single-use code that is replaced with access and refresh token later.

Is valued only if header parameter grant_type = “authorization_code”

 

Authorization

Parameter Required? Description
Username Yes Is given by Alpha3D
Password No NULL

 

Body parameters

NB! Only valued if header parameter grant_type = “password”

Parameter Type Required? Description
email string Yes User’s email
password string Yes User’s password

 

Output

HTTP response code Return content
1 400 Error messages:

  1. “Unsupported grant_type”
2 401 Error messages:

  1. “Incorrect email or password”
3 200 Return structure:

Parameter Explanation
access_token Access token to access Alpha3D externally
token_type “bearer”
refresh_token Refresh token to refresh log in session
expires_in Access token expiration time
scope “external”
sub User’s email to whom the session belongs to
roles User’s role in Alpha3D
company Company of the user who logged in
uuid User’s UUID
email User’s email who logged in
jti Unique identifier

 

 

Querying products

Description

The goal of this service is to provide a query for partner applications to retrieve all logged in user’s approved products that have a provided 3D asset file format.

 

Request

Method HTTP request Description
GET /alphaar/api/ext/pr
oduct/approved
Returns user’s approved products that have a provided 3D asset file format

 

Input

Parameter Type Required? Description
bearerToken string Yes User’s bearer token from the Login service
fileFormat string Yes 3D model file format that the user wants to query the products for.

Accepted values:

  1. GLB
  2. GLTF
  3. USD

 

Output

HTTP response code Return content
1 401 Error messages:

  1. “Invalid token”
2 400 Error messages:

  1. “Alpha3D is restricted due to an unpaid invoice. Please visit Alpha3D for more information.”
  2. “Provided 3D asset file format is not supported in Alpha3D”
3 200 Return message (list of products):

Parameter Explanation
uuid Product’s UUID
brandName Product’s brand name
modelName Product’s model name
thumbnail Thumbnail image content

 

 

Querying 3D models

Description

The goal of this service is to provide a query for partner applications to retrieve a 3D asset file for a provided product UUID and file format.

 

Request

Method HTTP request Description
GET /alphaar/api/ext/ass
et/{productUuid}
Returns a provided product’s 3D asset file

 

Input

Parameter Type Required? Description
bearerToken string Yes User’s bearer token from the Login service
fileFormat string Yes 3D model file format that the user wants query the products.

Accepted values:

  1. GLB
  2. USD
  3. GLTF
  4. ALL

 

Output

HTTP response code Return content
1 401 Error messages:

  1. “Invalid token”
2 400 Error messages:

  1. “Alpha3D is restricted due to an unpaid invoice. Please visit Alpha3D for more information.”
  2. “Provided file format is wrong. Accepted values: “GLB”, “USD”, “GLTF” or “ALL””
  3. “Product with provided UUID does not exist or is not accepted.”
3 200 Return message (list of files):

Parameter Explanation
attachmentUuid Attachment’s UUID
fileName File’s name
fileType File type
base64 File content
extension File extention. Possible values:

  • glb
  • gltf
  • usd

 

 

Generate 3D models

Description

This service’s goal is to provide a query for partner applications to generate a 3D asset file for a provided project name, category, product name, and image.

 

Request

Method HTTP request Description
POST /alphaar/api/ext/project Returns a response message

 

Input

Parameter Type Required? Description
bearerToken string Yes User’s bearer token from the Login service
ProjectName string No Provided name for the project. If empty then generated automatically using the same logic as in the system (“Project ”).
projectCategory string Yes Accepted values:

  1. ANYTHING
  2. SOFA
  3. SNEAKERS
productName string Yes Product model name.
For “ANYTHING” category, this is the text describing the 3D model that user wants to generate.
imageType string(JPG,JPEG,PNG,WEBP) Yes/No Mandatory when projectCategory is “SOFA” or “SNEAKERS”.
image base64 Yes/No Mandatory when projectCategory is “SOFA” or “SNEAKERS”.

 

Output

HTTP response code Return content
1 401 Error messages:

  1. “Invalid token”
2 400 Error messages:

  1. “Alpha3D is restricted due to an unpaid invoice. Please visit Alpha3D for more information.”
  2. “One or many required request parameters are missing or not correct”
3 200 Generated project UUID