Appearance
Image generation failures
Image generation can fail even when the request format is valid. Most failures come from provider safety rules, unsupported prompt goals, reference image issues, temporary capacity, or rate limits. Pixapi keeps the API response, task state, and credit ledger aligned so your product can show a clear next step.
Quick triage
| What you see | Likely cause | Next action |
|---|---|---|
| Safety or policy wording | Prompt or reference image triggered provider safety checks | Remove restricted content, simplify the prompt, and retry with a safer description. |
| No image or text-only output | The model responded without an image part | Inspect response parts, requested modality, prompt complexity, and model support. |
Timeout, 503, or provider unavailable | Temporary provider capacity or network issue | Retry with bounded backoff and keep the same payload for one verification request. |
| Upload or reference-image error | Unsupported format, large file, corrupted file, or inaccessible URL | Use PNG, JPEG, or WebP, keep files small, and make sure URLs are reachable by Pixapi. |
429 or rate-limit wording | Account, model, or provider-side rate pressure | Back off with jitter and queue non-urgent jobs instead of retrying in a tight loop. |
insufficient_credits | Balance was too low before generation started | Ask the user to top up credits; this is not a generation failure refund case. |
Common causes
Safety and restricted content
Image providers may block prompts or reference images involving explicit sexual content, graphic violence, hate or harassment, self-harm, illegal activity, or inappropriate minor-related content. These rules can apply during generation, not only during request validation.
Watermark removal and copyrighted material
Requests to remove watermarks, reproduce protected characters, copy famous IP, or imitate public figures can be rejected or return no usable image. Reframe the request around an original concept, licensed assets, or a general visual style.
Prompt complexity
Very long prompts, conflicting instructions, dense text requirements, or too many subjects can make the model produce text-only output, partial output, or no image. Reduce the request to the main subject, style, composition, and output requirements before adding detail back.
Reference image problems
Image editing and image-to-image requests depend on the input asset. Check that the image URL is reachable, the file is not corrupted, and the format is supported. If a signed URL expires quickly, upload the image again or use a longer-lived URL.
Temporary provider issues
Provider capacity, rate limits, and upstream timeouts can happen intermittently. For production apps, retry only a small number of times with exponential backoff and jitter. Keep the same model, payload, and reference image for one retest so the diagnostic signal stays clean.
Refunded credits
If credits were consumed or reserved but the image generation job fails before a billable output is delivered, Pixapi returns the affected credits to your account. The credit ledger shows these rows as Refunded.
Open Credits to review refunded credit rows. A refunded row means your balance was restored; it does not mean the original prompt will succeed unchanged.
What to log before contacting support
Include the request id or task id, model id, timestamp, sanitized prompt, input image format and size, response error code, and whether credits were refunded. This lets support distinguish policy blocks, payload issues, provider downtime, and billing reconciliation quickly.