Create a run

curl --request POST \
  --url https://api.zerogen.com/v1/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "black-forest-labs/flux-2-pro/generate",
  "prompt": "A lighthouse at dawn, fog over the water",
  "output": {
    "count": 1
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'black-forest-labs/flux-2-pro/generate',
    prompt: 'A lighthouse at dawn, fog over the water',
    output: {count: 1}
  })
};

fetch('https://api.zerogen.com/v1/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.zerogen.com/v1/runs"

payload = {
    "model": "black-forest-labs/flux-2-pro/generate",
    "prompt": "A lighthouse at dawn, fog over the water",
    "output": { "count": 1 }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "projectId": "<string>",
  "model": "<string>",
  "modelVersion": "<string>",
  "status": "queued",
  "outputs": [
    {
      "index": 4503599627370495,
      "status": "queued",
      "asset": {
        "id": "<string>",
        "mimeType": "<string>",
        "width": 4503599627370495,
        "height": 4503599627370495,
        "durationMs": 4503599627370495,
        "resourceUri": "<string>"
      },
      "error": {
        "code": "<string>",
        "message": "<string>",
        "retryable": true,
        "param": "<string>",
        "details": {}
      },
      "warnings": [
        {
          "code": "<string>",
          "message": "<string>"
        }
      ],
      "draft": {
        "expiresAt": "2023-11-07T05:31:56Z",
        "upscalable": true,
        "upscale": "upscaling",
        "finalResolution": "<string>",
        "finalAssetId": "<string>"
      }
    }
  ],
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  },
  "billing": {
    "mode": "platform",
    "state": "held",
    "quotedMicroUsd": 4503599627370495,
    "heldMicroUsd": 4503599627370495,
    "chargedMicroUsd": 4503599627370495,
    "hold": {
      "state": "running",
      "endedAt": "2023-11-07T05:31:56Z"
    }
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "finishedAt": "2023-11-07T05:31:56Z"
}

{
  "id": "<string>",
  "projectId": "<string>",
  "model": "<string>",
  "modelVersion": "<string>",
  "status": "queued",
  "outputs": [
    {
      "index": 4503599627370495,
      "status": "queued",
      "asset": {
        "id": "<string>",
        "mimeType": "<string>",
        "width": 4503599627370495,
        "height": 4503599627370495,
        "durationMs": 4503599627370495,
        "resourceUri": "<string>"
      },
      "error": {
        "code": "<string>",
        "message": "<string>",
        "retryable": true,
        "param": "<string>",
        "details": {}
      },
      "warnings": [
        {
          "code": "<string>",
          "message": "<string>"
        }
      ],
      "draft": {
        "expiresAt": "2023-11-07T05:31:56Z",
        "upscalable": true,
        "upscale": "upscaling",
        "finalResolution": "<string>",
        "finalAssetId": "<string>"
      }
    }
  ],
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  },
  "billing": {
    "mode": "platform",
    "state": "held",
    "quotedMicroUsd": 4503599627370495,
    "heldMicroUsd": 4503599627370495,
    "chargedMicroUsd": 4503599627370495,
    "hold": {
      "state": "running",
      "endedAt": "2023-11-07T05:31:56Z"
    }
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "finishedAt": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

POST

runs

Create a run

curl --request POST \
  --url https://api.zerogen.com/v1/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "black-forest-labs/flux-2-pro/generate",
  "prompt": "A lighthouse at dawn, fog over the water",
  "output": {
    "count": 1
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'black-forest-labs/flux-2-pro/generate',
    prompt: 'A lighthouse at dawn, fog over the water',
    output: {count: 1}
  })
};

fetch('https://api.zerogen.com/v1/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.zerogen.com/v1/runs"

payload = {
    "model": "black-forest-labs/flux-2-pro/generate",
    "prompt": "A lighthouse at dawn, fog over the water",
    "output": { "count": 1 }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "projectId": "<string>",
  "model": "<string>",
  "modelVersion": "<string>",
  "status": "queued",
  "outputs": [
    {
      "index": 4503599627370495,
      "status": "queued",
      "asset": {
        "id": "<string>",
        "mimeType": "<string>",
        "width": 4503599627370495,
        "height": 4503599627370495,
        "durationMs": 4503599627370495,
        "resourceUri": "<string>"
      },
      "error": {
        "code": "<string>",
        "message": "<string>",
        "retryable": true,
        "param": "<string>",
        "details": {}
      },
      "warnings": [
        {
          "code": "<string>",
          "message": "<string>"
        }
      ],
      "draft": {
        "expiresAt": "2023-11-07T05:31:56Z",
        "upscalable": true,
        "upscale": "upscaling",
        "finalResolution": "<string>",
        "finalAssetId": "<string>"
      }
    }
  ],
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  },
  "billing": {
    "mode": "platform",
    "state": "held",
    "quotedMicroUsd": 4503599627370495,
    "heldMicroUsd": 4503599627370495,
    "chargedMicroUsd": 4503599627370495,
    "hold": {
      "state": "running",
      "endedAt": "2023-11-07T05:31:56Z"
    }
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "finishedAt": "2023-11-07T05:31:56Z"
}

{
  "id": "<string>",
  "projectId": "<string>",
  "model": "<string>",
  "modelVersion": "<string>",
  "status": "queued",
  "outputs": [
    {
      "index": 4503599627370495,
      "status": "queued",
      "asset": {
        "id": "<string>",
        "mimeType": "<string>",
        "width": 4503599627370495,
        "height": 4503599627370495,
        "durationMs": 4503599627370495,
        "resourceUri": "<string>"
      },
      "error": {
        "code": "<string>",
        "message": "<string>",
        "retryable": true,
        "param": "<string>",
        "details": {}
      },
      "warnings": [
        {
          "code": "<string>",
          "message": "<string>"
        }
      ],
      "draft": {
        "expiresAt": "2023-11-07T05:31:56Z",
        "upscalable": true,
        "upscale": "upscaling",
        "finalResolution": "<string>",
        "finalAssetId": "<string>"
      }
    }
  ],
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  },
  "billing": {
    "mode": "platform",
    "state": "held",
    "quotedMicroUsd": 4503599627370495,
    "heldMicroUsd": 4503599627370495,
    "chargedMicroUsd": 4503599627370495,
    "hold": {
      "state": "running",
      "endedAt": "2023-11-07T05:31:56Z"
    }
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "startedAt": "2023-11-07T05:31:56Z",
  "finishedAt": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "param": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

A ZeroGen API key: zg_ for a live key, zg_test_ for a test key.

Headers

Idempotency-Key

string

Makes retries safe: a retry with the same key and body returns the first response for 24 hours instead of repeating the work. Reusing a key with a different body returns 409.

Required string length: 1 - 255

Pattern: ^[\x21-\x7e]+$

Prefer

string

wait=N holds the response up to N seconds (at most 60) until the run ends.

Pattern: ^wait=\d+$

Example:

"wait=30"

Body

application/json

model

string

required

Maximum string length: 200

Pattern: ^[a-z0-9]+(?:[.-][a-z0-9]+)*\/[a-z0-9]+(?:[.-][a-z0-9]+)*\/[a-z0-9]+(?:[.-][a-z0-9]+)*$

prompt

string

Maximum string length: 20000

inputs

object[]

Maximum array length: 50

Option 1
Option 2

Show child attributes

output

object

Show child attributes

voice

string

Speech models only: the voice to read the prompt in, from the model's voices

Pattern: ^library:[A-Za-z0-9]{1,64}$

parameters

object

Only the parameters the model's schema lists

Show child attributes

maxCostMicroUsd

integer

Refuse to start when the quote exceeds this amount

Required range: 0 <= x <= 9007199254740991

test

object

Test keys only: rehearse each output's outcome; live keys are refused when it is present

Show child attributes

projectId

string

The project the outputs land in; the organization's default project when omitted. Test keys use their sandbox.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

folderId

string | null

A folder in that project to file the outputs in; null or omitted for Unfiled

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

naming

object

Show child attributes

Response

The run has ended, within the requested wait.

string

required

projectId

string

required

The project that holds the outputs

model

string | null

required

Maximum string length: 200

Pattern: ^[a-z0-9]+(?:[.-][a-z0-9]+)*\/[a-z0-9]+(?:[.-][a-z0-9]+)*\/[a-z0-9]+(?:[.-][a-z0-9]+)*$

modelVersion

string | null

required

status

enum<string>

required

Available options:

queued,

running,

succeeded,

partial,

failed,

cancelled

outputs

object[]

required

Show child attributes

error

object | null

required

Show child attributes

billing

object

required

Show child attributes

createdAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

startedAt

string<date-time> | null

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

finishedAt

string<date-time> | null

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Overview

Endpoints

Create a run

Authorizations

Headers

Body

Response