Polling strategy

Generation tasks are asynchronous. You submit a job, receive a taskId, and poll until the task reaches a terminal state. This guide documents the behaviour you can rely on.

The grace window

For each pending task we remember the last time we asked the upstream provider about it. Inside a 30-second grace window we return the cached DB state and skip the upstream round-trip. Outside the window we ask the provider again and refresh the DB.

The callback webhook delivers terminal state without any polling at all — the 30-second window simply prevents a busy client from DoS-ing the provider on our behalf.

Practical rules:

• Polling every 2 seconds is safe and recommended.
• Polling faster than 2 seconds gains you nothing — the response inside the grace window is identical to the previous one.
• Polling slower than 30 seconds is fine, but each call will hit the provider.

Recommended loop

TASK_ID="tsk_..."
INTERVAL=2
MAX_WAIT=180   # 3 minutes, covers even slow video models
ELAPSED=0

while [ $ELAPSED -lt $MAX_WAIT ]; do
RESPONSE=$(curl -s https://gptimage2api.org/api/ai/tasks/$TASK_ID \
  -H "Authorization: Bearer $API_KEY")

STATUS=$(echo "$RESPONSE" | jq '.status')

case "$STATUS" in
  0) sleep $INTERVAL; ELAPSED=$((ELAPSED + INTERVAL));;
  1) echo "$RESPONSE" | jq '.'; exit 0;;
  2) echo "$RESPONSE" | jq '{errorCode, errorMessage}'; exit 1;;
  *) echo "Unexpected response: $RESPONSE"; exit 1;;
esac
done

echo "Timed out after ${MAX_WAIT}s"
exit 124

Exponential backoff (optional)

For long-running video jobs you can start at 2 seconds and cap at 15:

INTERVAL=2
while true; do
  # ... (same as above)
  sleep $INTERVAL
  INTERVAL=$(( INTERVAL < 15 ? INTERVAL * 2 : 15 ))
done

What about webhooks?

Webhook delivery is on the roadmap. Until then, polling is the only callback mechanism.