Start a Job

A general guide for submitting jobs via API

Once your Apps, Partitioning Engines, and Assembling Engines are ready, and you've linked them together using Job Templates, you're prepared to launch test and production jobs.

ByteNite utilizes an API to handle job requests — the Customer API— simplifying and standardizing the interaction with our server.

To begin using the API and familiarizing yourself with its endpoint, we recommend setting up a Postman collection. You can find more details at Create a Postman collection from ByteNite's OAS.

Below are the steps to configure and send a new job request, broken down and explained. You may refer to the official Jobs reference for a complete parameter list, response codes, and default code examples.

1

Get an Access Token

Begin by obtaining a temporary access token to authenticate your requests.

Request URL

POST https://api.bytenite.com/v1/auth/access_token

---

Main ref: POST /access_token

Body

Name	Type	Description
apiKey	string	Your ByteNite API Key

Response [200]

Name	Type	Description
token	string	Your ByteNite access token
expiresIn	string	An expiration timeout in seconds

Example:

POST /auth/access_token

import requests

response = requests.post(
    "https://api.bytenite.com/v1/auth/access_token",
    json = {
        "apiKey": "ey2WmEsSMK7wdxpK5MaEHXeWCD5KEJZ79Koe68yrHL4kdnnTXT01hu2iss43BdaCCMgJ3dBh2IOVCycTt1mwkT3QR1dLxRFpK7TW7ExvcuCXio6nKsGjk9dYY8nbsFffrUVvYSQYsuQoF3NIb8sS4MDyZfOgGKZL9z8x22cwrwEck7vIokVhQ9fyWRVU2vwRiX3X4bQFuqTkkWCi5Vfy8IkGkga7ZPMPb21FxqK6cHRJ3zmI1JZZoZZxERnQcWJTpZRyCP4SNTuRm3ueVDNntFqYWYYrseNLcCIS42MpR00Z9rI9I5xxuQD6VQvHVrpOaPucg1E4Vw54xXr2LKEy9uHcM5WUQHkdfhiXo6zyVbZMrbjLpepgeS4nEja="
    }
)

token = response.json()["token"]

2

Create a New Job

Submit a new job request using an existing job template, and give it a name.

Request URL

POST https://api.bytenite.com/v1/customer/jobs

---

Main ref: POST /jobs

Headers

Name	Type	Description
Authorization	string	An active ByteNite access token

Body

Name	Type	Description
templateId	string	ID of the job template used for this job
name	string	A descriptive name for your job
description	string	An optional description with more information

Response [200]

Name	Type	Description
job	object	A job object, containing job metadata
↳ id	string	The job identifier (automatically generated)

Example:

POST /customer/jobs

response = requests.post(
    "https://api.bytenite.com/v1/customer/jobs",
    headers = {
        "Authorization": token
    },
    json = {
        "name": "My job with img-gen-diffusers template",
        "templateId": "img-gen-diffusers"
    }
)

jobId = response.json()["job"]["id"]

3

Submit a Data Source and Destination

Link a data source and destination to your job, specifying input and output options as documented in the Link Your Data Source guide.

Connecting data sources is optional: if your app doesn't require any input data to work, or doesn't output data, you can specify a bypass data source descriptor.

Request URL

PATCH https://api.bytenite.com/v1/customer/jobs/{jobId}/datasource

---

Main ref: PATCH /jobs/{jobId}/datasource

Path Params

Name	Type	Description
jobId	string	The jobIdof your new job

Headers

Name	Type	Description
Authorization	string	An active ByteNite access token

Body

Name	Type	Description
dataSource	object	A data source object, containing a dataSourceDescriptor and optional params
dataDestination	object	A data source object, containing a dataSourceDescriptor and optional params

Example:

PATCH /customer/jobs/{jobId}/datasource

response = requests.patch(
    f"https://api.bytenite.com/v1/customer/jobs/{jobId}/datasource",
    headers = {
        "Authorization": token
    },
    json = {  
        "dataSource": {
            "dataSourceDescriptor": "url",
            "params": {
                "@type": "type.googleapis.com/bytenite.data_source.HttpDataSource",
                "url": "https://storage.googleapis.com/my-public-bucket/my-input-file.txt"
            }
        },
        "dataDestination": {
            "dataSourceDescriptor": "bucket"
        }
    }
)

4

Submit Job Parameters

If your app, partitioner, or assembler expect parameters, provide them at this step. Parameters are organized under three keys: app, partitioner, and assembler for clarity.

If your template includes parameter schemas, the parameters you submit here will be validated immediately, and any errors will be returned.

Request URL

PATCH https://api.bytenite.com/v1/customer/jobs/{jobId}/params

---

Main ref: PATCH /jobs/{jobId}/params

Path Params

Name	Type	Description
jobId	string	The jobIdof your new job

Headers

Name	Type	Description
Authorization	string	An active ByteNite access token

Body

Name	Type	Description
app	object	A JSON object containing parameters as expected by your app
partitioner	object	A JSON object containing parameters as expected by your partitioning engine
assembler	object	A JSON object containing parameters as expected by your assembling engine

Example:

PATCH /customer/jobs/{jobId}/params

response = requests.patch(
    f"https://api.bytenite.com/v1/customer/jobs/{jobId}/params",
    headers = {
        "Authorization": token
    },
    json = {
        "partitioner": {
            "numImages": 20
        },
        "app": {
            "prompt": "A beautiful sunset over the jungle"
        },
        "assembler": {
            "outExtension": "jpeg"
        }
    }
)

5

Launch the Job

Run the job, including execution configurations if needed.

Please note that you need this call to initiate the processing of your job. Without this step, your job will remain in a draft state.

Request URL

POST https://api.bytenite.com/v1/customer/jobs/{jobId}/run

---

Main ref: POST /jobs/{jobId}/run

Path Params

Name	Type	Description
jobId	string	The jobIdof your new job

Headers

Name	Type	Description
Authorization	string	An active ByteNite access token

Body

Name	Type	Description
taskTimeout	integer	An optional timeout for tasks, in seconds. After this time, a task will be stopped.
jobTimeout	integer	An optional timeout for jobs, in seconds. After this time, the job and any running tasks will be stopped.
isTestJob	boolean	A flag for test jobs.

Example:

PATCH /customer/jobs/{jobId}/params

response = requests.post(
    f"https://api.bytenite.com/v1/customer/jobs/{jobId}/run",
    headers = {
        "Authorization": token
    },
    json = {
        "taskTimeout": 3600,
        "jobTimeout": 86400,
        "isTestJob": True
    }
)