Create an Instance

This endpoint provisions and launches a new Yotta Series GPU secure pod by specifying the GPU accelerator model (gpu_type), the required number of GPUs (gpu_count), and a pre-configured OS container image (gpu_image).

Create an Instance - Overview

The Yotta Series Instance API allows authenticated users to launch a Yotta Series GPU pod using three parameters: GPU type, GPU count, and pod image.

The endpoint accepts gpu_type, gpu_count, and gpu_image in the JSON request body. The response includes the instance ID, pod ID, hourly cost, and current provisioning status.

Use this endpoint to launch a Yotta Series GPU pod with a selected GPU configuration and an available image returned by the Yotta Series offers and OS images endpoints.

Endpoint

Property	Value
HTTP Method	POST
Endpoint	/yotta/create
Full URL	https://cloud.dataoorts.com/api/v1/yotta/create
Authentication	Bearer Token
Request Format	JSON
Response Format	JSON

Authentication

This endpoint requires a valid Dataoorts Unify API key.

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

HTTP

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 endpoint requires a JSON request body containing the GPU type, GPU count, and pod image.

Parameter	Type	Required	Description
gpu_type	String	Yes	The GPU model to use for the Yotta Series pod, such as NVIDIA_H200_141G.
gpu_count	Integer	Yes	The number of GPUs to provision for the pod.
gpu_image	String	Yes	The image identifier to use for the pod, selected from the available Yotta Series images.

Example Request Body

JSON

{
  "gpu_type": "NVIDIA_H200_141G",
  "gpu_count": 1,
  "gpu_image": "pytorch:2.9.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04"
}

Use a GPU config & image identifier that are available through the Yotta offers and OS images endpoints.

Request Examples

cURL - Use the following command to launch a Yotta Series GPU pod:

Bash

curl --request POST \
  --url "https://cloud.dataoorts.com/api/v1/yotta/create" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "gpu_type": "NVIDIA_H200_141G",
    "gpu_count": 1,
    "gpu_image": "pytorch:2.9.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04"
  }'

Replace YOUR_API_KEY with your actual Unify API key. Adjust GPU type, GPU count, and image according to your requirements.

Python Example Implementation

The following example uses the requests library to create a Yotta Series GPU pod. It reads the API key from an environment variable, handles unsuccessful HTTP responses, and checks the response format before processing the returned data.

Install the required dependency:

Bash

pip install requests

Python

import os
import requests


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


def create_yotta_instance(
    api_key: str,
    gpu_type: str,
    gpu_count: int,
    gpu_image: str,
) -> dict | None:
    """
    Launch a Yotta Series GPU pod.

    Args:
        api_key: Your Dataoorts Unify API key.
        gpu_type: The GPU model to provision.
        gpu_count: The number of GPUs to provision.
        gpu_image: The image identifier to use for the pod.

    Returns:
        The JSON response containing the pod launch details,
        or None if the API returns a non-JSON response.

    Raises:
        requests.exceptions.RequestException:
            If the HTTP request fails or returns an unsuccessful
            HTTP status code.
        ValueError:
            If the JSON response cannot be decoded.
    """
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    payload = {
        "gpu_type": gpu_type,
        "gpu_count": gpu_count,
        "gpu_image": gpu_image,
    }

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

    response.raise_for_status()

    content_type = response.headers.get("Content-Type", "")

    if "application/json" not in content_type.lower():
        print("Non-JSON response received:")
        print(response.text[:500])
        return None

    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_yotta_instance(
            api_key=api_key,
            gpu_type="NVIDIA_H200_141G",
            gpu_count=1,
            gpu_image=(
                "pytorch:2.9.0-py3.11-cuda12.8.1-"
                "cudnn-devel-ubuntu22.04"
            ),
        )

        if result is not None:
            print("Status:", result.get("status"))
            print("Message:", result.get("message"))

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

            print("\nYotta Pod Details")
            print("Instance ID:", data.get("instance_id"))
            print("Pod ID:", data.get("pod_id"))
            print("Status:", data.get("status"))
            print("Hourly Cost:", data.get("hourly_cost"))

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

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

Set your API key before running the script.

Linux / macOS

Bash

export DATAOORTS_API_KEY="YOUR_API_KEY"
python yotta_create.py

Windows PowerShell

PowerShell

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

The script submits the selected GPU configuration and image, then displays the returned instance ID, pod ID, provisioning status, and hourly cost.

Example Success Response

A successful request returns a JSON object containing the newly created instance details, a descriptive message, and the response status.

JSON

{
  "data": {
    "hourly_cost": 2.19,
    "instance_id": 4,
    "pod_id": "417346650508649256",
    "status": "provisioning"
  },
  "message": "Pod provisioning initiated successfully.",
  "status": "success"
}

The values above illustrate the response structure. Instance identifiers, pod IDs, and hourly costs may differ in subsequent API responses.

Response Fields

Field	Type	Description
status	String	Indicates result of the API request. A successful response returns success.
message	String	A descriptive message about the result of the pod creation request.
data	Object	Contains the details returned for the created Yotta Series pod.

Instance Record Fields

The data object contains the information returned after the pod creation request.

Field	Type	Description
data.instance_id	Integer	The identifier assigned to the instance.
data.pod_id	String	The identifier assigned to the Yotta pod.
data.status	String	Current status returned for pod. Example returns provisioning.
data.hourly_cost	Float	The hourly cost reported for the selected GPU configuration.

Understanding Instance Information

GPU Configuration

The gpu_type parameter specifies the GPU model, while gpu_count specifies the number of GPUs requested for the pod. Use the Yotta Series offers endpoint to review the available GPU types and configurations before submitting a creation request.

Pod Image

The gpu_image parameter specifies the image used to launch the pod. Use the Yotta Series OS images endpoint to retrieve the available image identifiers. Provide the exact identifier returned by that endpoint, including its version and other suffixes.

Instance and Pod Identification

The response includes instance_id and pod_id. These fields identify the created instance and its associated pod as reported by the API. Retain these identifiers when working with the pod through subsequent Yotta Series API operations.

Provisioning Status

The status field in the example response returns provisioning, and the message states that pod provisioning has been initiated successfully. A provisioning status indicates that the launch process has been initiated; it should not be treated as confirmation that the pod is ready for use. Check the relevant instance information endpoint for its latest status before proceeding.

Hourly Cost

The hourly_cost field reports the hourly cost returned for the selected GPU configuration. In the example response, the value is 2.19. The actual cost may vary depending on the selected GPU configuration. Review the corresponding offer details for the pricing information returned by the API.

Important Notes

1. Required Parameters: Provide all three required parameters: gpu_type, gpu_count, and gpu_image.

2. GPU Availability: Select a GPU type and configuration from the available Yotta Series offers.

3. Image Selection: Use a valid image identifier returned by the Yotta Series OS images endpoint.

4. Pod Provisioning: The response may return provisioning after the launch request has been accepted. Verify the latest pod status before assuming it is ready for use.

5. Instance Identification: Save returned instance_id & pod_id for subsequent pod managment operations.

6. Pricing Information: The hourly_cost field reports hourly cost returned by API for the selected GPU config.

7. Request Timeout: The example uses a timeout of 60 seconds. If a request times out, check the instance information before retrying the creation request because result of the original request may be uncertain.

8. API Key Security: Keep your API key confidential and store it in the DATAOORTS_API_KEY environment variable rather than hardcoding it in your application.

Error Handling

If the request fails, the API may return an unsuccessful HTTP status code or a response that does not match the expected JSON format.

Your application should handle authentication failures, invalid request parameters, network errors, request timeouts, server errors, & unexpected responses. The exact error codes & messages depend on API response.

In Python, response.raise_for_status() raises an exception for unsuccessful HTTP status codes. The example also checks the response content type and handles JSON decoding errors before processing the returned pod details.

Scenario	Recommended Handling
API key is missing	Set the DATAOORTS_API_KEY environment variable.
Authentication fails	Verify that API key is valid & included in Authorization header.
Invalid GPU type or count	Verify the selected GPU configuration against the available Yotta Series offers.
Invalid image identifier	Check the available images returned by the Yotta Series OS images endpoint.
HTTP request fails	Catch requests.exceptions.RequestException and inspect the error details.
Request times out	Check pod information before retrying the creation request.
Response is not JSON	Inspect the returned response text without attempting to parse it as JSON.
Response contains invalid JSON	Handle the JSON decoding error before accessing response fields.

Get Help and Support

For assistance with Yotta Series pod creation or API integration, Contact support team at [email protected].