Create an Instance

Create an Instance - Overview

The Orix Series Instance Creation API allows authenticated users to launch a new GPU instance by specifying the GPU configuration, number of GPUs, deployment region, machine type, and network type.

This endpoint supports automated GPU infrastructure provisioning and can be integrated into custom dashboards, deployment scripts, and resource management applications.

When an instance provisioning request succeeds, the API returns the instance ID, instance name, hourly cost, hardware specifications, and current provisioning status.

Important Note: Ensure that all request parameters are valid and match the available configurations returned by the Orix Offers API before submitting the request.

Endpoint

Property	Value
HTTP Method	`POST`
Endpoint	`/orix/create`
Full URL	`https://cloud.dataoorts.com/api/v1/orix/create`
Authentication	Bearer Token
Content Type	`application/json`
Response Format	JSON
Success Status	`201 Created`

Authentication

This endpoint requires a valid Dataoorts Unify API key.

Include your API key in the Authorization header using the Bearer authentication scheme.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Generate or manage your API key through the Dataoorts Unify API.

Keep your API key confidential and never expose it in public repositories or client-side applications.

Request Parameters

The request body must be sent as JSON.

Parameter	Type	Required	Description
`gpu_type`	String	Yes	The GPU model to use for the instance, such as `H200`.
`gpu_count`	Integer	Yes	The number of GPUs to allocate to the GPU Instance, such as `16`, `8`, `4`.
`region`	String	Yes	The deployment region associated with the selected offer, such as `US-SOUTHEAST-2`.
`machine_type`	String	Yes	The machine config type, such as `Virtual-Machine` or `Bare-Metal`, according to the supported values.
`network_type`	String	Yes	The network connection type requested for the GPU Instance, such as `Ethernet` or `InfiniBand`.

Important: Use the correct GPU type, GPU count, region, machine type, and network type. Refer to the Orix Offers API for available GPU configurations, regions, hardware specifications, and network details.

Request Examples

cURL - Use the following command to launch an Orix GPU instance:

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/orix/create" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "gpu_type": "H200",
    "gpu_count": 8,
    "region": "US-SOUTHEAST-2",
    "machine_type": "Virtual-Machine",
    "network_type": "Ethernet"
  }'

Replace YOUR_API_KEY with your actual Dataoorts Unify API key. Adjust the configuration parameters according to the available offers and your workload requirements.

Python Example Implementation

The following example uses the requests library to create an Orix instance and display its provisioning status, hourly cost, and hardware specifications.

Install the required dependency:

pip install requests

import os
import json
import requests


API_URL = "https://cloud.dataoorts.com/api/v1/orix/create"


def create_orix_instance(
    api_key: str,
    gpu_type: str,
    gpu_count: int,
    region: str,
    machine_type: str,
    network_type: str,
) -> dict:
    """
    Launch a new Orix GPU instance.

    Args:
        api_key: Your Dataoorts Unify API key.
        gpu_type: GPU model, such as H200.
        gpu_count: Number of GPUs to allocate.
        region: Deployment region identifier.
        machine_type: Machine configuration type.
        network_type: Network connection type.

    Returns:
        dict: The JSON response containing the provisioning result
              and instance details.

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the parameters are invalid or the response
            cannot be decoded as JSON.
    """
    if not isinstance(gpu_count, int) or isinstance(gpu_count, bool):
        raise ValueError("gpu_count must be an integer.")

    if gpu_count <= 0:
        raise ValueError("gpu_count must be greater than zero.")

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "gpu_type": gpu_type,
        "gpu_count": gpu_count,
        "region": region,
        "machine_type": machine_type,
        "network_type": network_type,
    }

    response = requests.post(
        API_URL,
        headers=headers,
        json=payload,
        timeout=120,
    )

    response.raise_for_status()

    try:
        return response.json()
    except requests.exceptions.JSONDecodeError as exc:
        raise ValueError(
            "The API returned an invalid JSON response."
        ) from exc


if __name__ == "__main__":
    api_key = os.getenv("DATAOORTS_API_KEY")

    if not api_key:
        raise RuntimeError(
            "Set the DATAOORTS_API_KEY environment variable."
        )

    try:
        result = create_orix_instance(
            api_key=api_key,
            gpu_type="H200",
            gpu_count=8,
            region="US-SOUTHEAST-2",
            machine_type="Virtual-Machine",
            network_type="Ethernet",
        )

        print("Status:", result.get("status"))
        print("Message:", result.get("message"))

        instance = result.get("data", {})

        print("Instance ID:", instance.get("instance_id"))
        print("Instance Name:", instance.get("instance_name"))
        print("Hourly Cost:", instance.get("hourly_cost"))
        print("Instance Status:", instance.get("status"))
        print("Hardware Specifications:")
        print(json.dumps(instance.get("specs", {}), indent=2))

    except requests.exceptions.RequestException as exc:
        print(f"API request failed: {exc}.")

    except ValueError as exc:
        print(f"Invalid request or response: {exc}.")

Set your API key before running the script.

Linux / macOS

export DATAOORTS_API_KEY="YOUR_API_KEY"
python create_orix_instance.py

Windows PowerShell

$env:DATAOORTS_API_KEY="YOUR_API_KEY"
python create_orix_instance.py

The script submits the provisioning request and displays the instance details returned by the API.

Example Success Response

When an instance provisioning request succeeds, the API returns a JSON response similar to the following.

HTTP Status: 201 Created

{
  "data": {
    "hourly_cost": 33.52,
    "instance_id": 4,
    "instance_name": "vm-h200",
    "specs": {
      "gpu_count": 8,
      "ram_gb": 2048,
      "storage_gb": 14307,
      "vcpus": 224
    },
    "status": "provisioning"
  },
  "message": "Instance Provisioning Initiated Successfully.",
  "status": "success"
}

The values shown above illustrate the response structure. The actual instance ID, name, hourly cost, and specifications depend on the configuration selected for the request.

Response Fields

Field	Type	Description
`status`	String	Indicates the result of the API request. A successful response API returns `success`.
`message`	String	A confirmation message indicating that instance provisioning was initiated successfully.
`data`	Object	Contains the details of the newly requested instance.
`data.instance_id`	Integer	The identifier assigned to the instance.
`data.instance_name`	String	The instance name returned by the API.
`data.hourly_cost`	Float	The hourly cost reported for the instance.
`data.status`	String	Current status reported by the API, such as `provisioning`.
`data.specs`	Object	Contains the hardware specifications returned for the instance.

Hardware Specification Fields

The data.specs object contains the hardware details associated with the created instance.

Field	Type	Description
`specs.gpu_count`	Integer	Number of GPUs allocated to the Instance.
`specs.ram_gb`	Number	System RAM capacity in GB.
`specs.storage_gb`	Number	NVMe Storage capacity in GB.
`specs.vcpus`	Number	Number of vCPU cores reported for Instance.

Understanding the Instance Creation Process

After submitting the request:

Dataoorts API processes the instance creation request using the supplied GPU configuration, region, machine type, and network type.
If the request is accepted, the API returns the instance information and provisioning status.
The returned data.status may be provisioning while the instance is being prepared.
Use the returned instance_id when calling other Orix endpoints that require an instance identifier.

A successful API response confirms that provisioning was initiated successfully. It does not necessarily mean the instance is fully operational or ready to accept connections.

Important Notes

1. Valid Configuration: Ensure that gpu_type, gpu_count, region, machine_type, and network_type match supported configurations.

2. GPU Availability: Check the latest Orix offers before submitting the request. Available configurations and resources may change.

3. Provisioning Status: The instance may initially have a provisioning status. Check its status before relying on it for production workloads.

4. Hourly Cost: The hourly_cost field reports the cost returned by the API. Review the selected configuration and applicable pricing information before launching an instance.

5. Handle Request Timeouts Carefully: If request time out or returns error, verify whether Instance was created before retrying. Server may have processed provisioning request even if client did not receive response.

Error Handling

If request fails, API may return unsuccessful HTTP status code & JSON response containing an error message.

Your application should handle authentication failures, invalid configuration parameters, unavailable resources, network errors, request timeouts, server errors, and unexpected response formats. The exact error codes and messages depend on the API response.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. Do not assume that every response contains the same fields as a successful response.

Get Help and Support

For assistance with Orix instance creation, GPU configuration, or API Integration, Contact the Dataoorts AI Cloud Support Team at [email protected].