Create a generation

Validates, prices, reserves and starts one generation in a single call. Send Prefer: wait=N to hold the response until it ends. Nothing is charged unless every check passes.

Needs the generations:create scope.

POST /generations

Create a generation

cURL

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
  }
}
'

200

{
  "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"
}

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

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

200

application/json

The generation has ended, within the requested wait.

id · 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))$