Create a generation

curl --request POST \
  --url https://api.zerogen.com/v1/generations \
  --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/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

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

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

generations

Create a generation

curl --request POST \
  --url https://api.zerogen.com/v1/generations \
  --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/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

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

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 generation 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

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 generation 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 generation

Authorizations

Headers

Body

Response