Generate

Endpoint

POST /v1/image/generate

Creates an image generation. Returns 202 Accepted (async, default) or 200 OK (sync, ?wait=true).

Request body

{
  "model_identifier": "gpt-image-2",
  "prompt": "A cinematic sunset over snow-capped mountains, ultra detailed",
  "params": {
    "quality": "high",
    "num_images": 1,
    "output_format": "png"
  },
  "image_urls": []
}

Field	Type	Required	Description
`model_identifier`	string	Yes	Model to use — see Models
`prompt`	string	Yes	Text description
`params`	object	No	Model-specific parameters
`image_urls`	array	No	Reference / edit images (hosted URLs or `data:` URIs)

Async (default) — `202 Accepted`

The request returns immediately with a job envelope. Poll poll_url or open stream_url to get the result.

{
  "id": "550e8400-e29b-41d4-a716-446655440015",
  "status": "queued",
  "model": "gpt-image-2",
  "estimated_cost": 0.10,
  "poll_url": "/public/v1/image/generations/550e8400-e29b-41d4-a716-446655440015",
  "stream_url": "/public/v1/image/generations/550e8400-e29b-41d4-a716-446655440015/stream"
}

Synchronous — `?wait=true`

POST /v1/image/generate?wait=true

The connection is held open until the generation completes (up to ~60 s) and returns the result inline:

{
  "id": "550e8400-e29b-41d4-a716-446655440015",
  "status": "completed",
  "model": "gpt-image-2",
  "prompt": "A cinematic sunset over snow-capped mountains, ultra detailed",
  "images": [
    { "url": "https://storage.googleapis.com/...signed...", "width": 1024, "height": 1024 }
  ],
  "cost_credits": 0.10,
  "created_at": "2026-06-22T10:00:00Z",
  "completed_at": "2026-06-22T10:00:18Z"
}

If the model exceeds the hold window, the response falls back to 202 Accepted with the job envelope — the generation continues server-side, nothing is lost. Always branch on the HTTP status code (or the status field), not on an assumption about the request mode.

Examples

Async + poll

JOB=$(curl -s -X POST https://api.goodtake.ai/v1/image/generate \
  -H "Authorization: Bearer $GOODTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_identifier":"gpt-image-2","prompt":"a red fox in snow","params":{"quality":"high"}}')

ID=$(echo "$JOB" | jq -r .id)

curl -s "https://api.goodtake.ai/v1/image/generations/$ID" \
  -H "Authorization: Bearer $GOODTAKE_API_KEY" | jq '.status, .images'

Synchronous (Seedream)

curl -s -X POST "https://api.goodtake.ai/v1/image/generate?wait=true" \
  -H "Authorization: Bearer $GOODTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_identifier":"seedream-4-5-251128","prompt":"a neon city street","params":{"size":"2K"}}' \
  | jq '.images[].url'

Image editing (gpt-image-2)

curl -s -X POST "https://api.goodtake.ai/v1/image/generate?wait=true" \
  -H "Authorization: Bearer $GOODTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_identifier": "gpt-image-2",
    "prompt": "add dramatic storm clouds above the mountains",
    "image_urls": ["https://example.com/mountains.jpg"],
    "params": {"quality": "high"}
  }' | jq '.images[].url'

Error codes

Status	Meaning
`400`	Invalid body, unknown model, unsupported param, or invalid `image_urls`
`401`	Missing or invalid API key
`402`	Insufficient credits

Unsupported param response:

{
  "error": "unsupported param \"foo\" for model \"gpt-image-2\"",
  "supported": ["image_size", "mask_url", "num_images", "output_format", "quality"]
}

Generate

On this page