Ernie Image Turbo API, Ernie Image 1.0 API - AI Image Generation APIs

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Add the X-Webhook-URL header to your generate request to receive a POST callback instead of polling.

X-Webhook-URL: https://your-server.com/webhook/callback

Request Parameters - Ernie Image Turbo generate request

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'ernie-image-turbo' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "ernie-image-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "ernie-image-turbo",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/ernie-image-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "ernie-image-turbo_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ernie-image-turbo",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ernie-image-turbo_019dxxxx/output.jpeg"],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Authentication

All requests require an API key passed via header.

Request Parameters - Ernie Image generate request

Response

{
  "request_id": "ernie-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/ernie-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response Fields - Ernie Image generate request

Request Headers

Response Handling

Common status codes for Ernie Image generate request.

Error Responses

{
  "error": "Invalid parameter: prompt is required"
}

{
  "error": "Resource not found"
}

Status Workflow

This API uses an asynchronous workflow. After submitting a request, poll the status endpoint until completion.

Status Values

Status Flow

Submit → QUEUED → PROCESSING → COMPLETED
                     ↘ FAILED
                     ↘ ERROR

Typical Workflow

1. Submit request to /ernie-image-request
2. Receive request_id in response
3. Periodically poll /v2/requests/status/{request_id} every 2–3 seconds
4. Continue polling until status is COMPLETED, FAILED, or ERROR
5. When COMPLETED, extract image URLs from the output

Request Parameters - Ernie Image check status

Response

{
  "request_id": "ernie-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "ernie-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/ernie-image_019dxxxx/output.jpeg"
    ],
    "media_type": "image/jpeg"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}

Response Fields - Ernie Image check status

Request Headers

Response Handling

Common status codes for Ernie Image check status.

Notes & Tips

1. Poll the status endpoint every 2–3 seconds until COMPLETED, FAILED, or ERROR is returned.
2. Implement exponential backoff for retry logic on ERROR or 500 responses.
3. Use detailed, descriptive prompts for optimal results — include lighting, style, mood, and composition.
4. Enable enable_prompt_expansion for non-native English prompts to improve interpretation.
5. Use seed to reproduce identical outputs for iterative refinement.
6. Prefer sync_mode: true only for small-scale or testing use cases — CDN URLs are more efficient for production.
7. For best quality, use num_inference_steps between 50–100 and guidance_scale between 5–7.
8. The output format defaults to jpeg; use png for transparency support.