Get started
Quickstart
Submit a generation request and retrieve its result.
This guide uses the REST API so you can see the complete request lifecycle. It takes about five minutes.
#Prerequisites
- A Higgsfield Console account
- An API key ID and secret
-
curlandjq
Warning
API credentials grant access to your account and its balance. Use them only in server-side code and never commit them to source control.
#1. Configure credentials
bash
export HF_API_KEY_ID="your-api-key-id"
export HF_API_KEY_SECRET="your-api-key-secret"
export IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')
#2. Submit a generation
bash
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url https://api.higgsfield.ai/xai/grok-imagine-image-2.0 \
--header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
--data '{
"prompt": "A quiet alpine lake at sunrise, editorial photography"
}')
echo "$RESPONSE" | jq
export REQUEST_ID=$(echo "$RESPONSE" | jq --raw-output '.request_id')
The initial response has the queued status:
json
{
"status": "queued",
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
"status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
"cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel"
}
If submission times out before you receive this response, repeat it with the same IDEMPOTENCY_KEY. See Idempotent requests.
#3. Check the result
bash
curl --silent --show-error --fail-with-body \
--url "https://api.higgsfield.ai/requests/${REQUEST_ID}/status" \
--header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" | jq
Repeat the status request until it reaches a terminal state. A completed image request returns:
json
{
"status": "completed",
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
"status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
"cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel",
"images": [
{
"url": "https://cdn.example.com/generated-image.jpg"
}
]
}
The other terminal statuses are failed, nsfw, and canceled.
#Next steps
Use an SDK
Prepare for production
Submit and wait for results with Python or TypeScript.
Add backoff, timeouts, terminal-state handling, and webhooks.
#Related topics
Was this page helpful?