Running a serverless endpoint

Note:
Before starting, ensure you have your Snowcell API key, which is required for both authentication and billing. Keep this key secure! Additionally, remember to retrieve your results within 30 minutes, as your inputs and outputs are automatically deleted for privacy reasons.

Overview

In this section, we’ll explore how Snowcell’s API works. The API is asynchronous, meaning when you submit a request, you’ll receive a job ID almost instantly. We’ll walk you through how to use this job ID to monitor the job’s progress and retrieve the results when ready.

We’ll use an example leveraging Snowcell’s GPU Rendering endpoint.

Create a Serverless Worker

First, let’s set up your serverless worker. Navigate to the Snowcell interface and choose Quick Deploy. Next, select the GPU Rendering v1.0 option. Choose a GPU with enough memory, for example, a 32 GB GPU, and click Deploy. Here’s an example endpoint you could use:
https://api.snowcell.io/v2/{ID}/render

Start Your Job

To start a job, send a request like the one shown below, passing the required parameters to the API to begin the rendering process:

curl -X POST https://api.snowcell.io/v2/{ID}/run \  
    -H 'Content-Type: application/json' \  
    -H 'Authorization: Bearer [Your API Key]' \  
    -d '{"input": {"scene": "Spaceship flying over a futuristic city at night."}}'

This request sends a scene description to Snowcell's API. After making the request, you’ll receive a response containing a job ID, like this:

{  
  "id": "b12345cd-6789-0efg-hijk-1234567890lm",  
  "status": "IN_QUEUE"  
}

Check the Status of Your Job

Once you have the job ID, you can check the status of the job as it processes. Use the following command, replacing the job ID:

curl https://api.snowcell.io/v2/{ID}/status/b12345cd-6789-0efg-hijk-1234567890lm \  
    -H 'Content-Type: application/json' \  
    -H 'Authorization: Bearer [Your API Key]'

If the job is still in progress, you’ll receive a response like this:

{  
  "delayTime": 1800,  
  "id": "b12345cd-6789-0efg-hijk-1234567890lm",  
  "input": { "scene": "Spaceship flying over a futuristic city at night." }, 
  "status": "IN_PROGRESS"  
}

Get the Completed Job Status

Once your job is complete, the final response will include the output:

{  
  "delayTime": 2200,  
  "executionTime": 5000,  
  "id": "b12345cd-6789-0efg-hijk-1234567890lm",  
  "output": [
    { 
      "rendered_image": "base64encodedimage", 
      "seed": 76543 
    },  
  ]
  "status": "COMPLETED"  
}

Retrieve and Save the Output

To save the rendered output, use this command:

curl https://api.snowcell.io/v2/{ID}/status/b12345cd-6789-0efg-hijk-1234567890lm \ 
    -H 'Content-Type: application/json' \ 
    -H 'Authorization: Bearer [Your API Key]' | jq . > render_output.json

Note:
Make sure to retrieve your output within 1 hour, as Snowcell automatically deletes the results after that period for privacy protection.

View Your Results

Once you have the output saved, you’ll need to decode the base64-encoded image. Below is an example of how to do that using Python:

import json 
import base64  

def decode_image(json_path, output_image_path):`  
    with open(json_path, "r") as file:`  
        data = json.load(file)`  
    image_data = data["output"][0]["rendered_image"]`  
    decoded_image = base64.b64decode(image_data)`  
    with open(output_image_path, "wb") as image_file:`  
        image_file.write(decoded_image)`  
    print(f"Image saved as {output_image_path}")`  

# Usage  
decode_image("render_output.json", "rendered_scene.png")

Conclusion

You’ve now successfully launched a serverless endpoint on Snowcell’s GPU cloud, rendering a scene using our API. This flexibility allows you to integrate GPU-heavy workloads like rendering, AI, or machine learning into your workflows with ease.