hiapi "model not available" errors: causes and fixes

If POST https://api.hiapi.ai/v1/tasks rejects a request because the model is unavailable or the request is invalid, the task was not created. Check the exact model name and request fields against the current model documentation before retrying.

Common causes

1. The model name is stale or incomplete. HiAPI model names are not all shaped the same way. Some are bare names, while others include a modality path. GPT Image 2 text-to-image requests use gpt-image-2/text-to-image.
2. A typo, casing difference, or hidden whitespace changed the name. Copy the model name from the current docs instead of typing it from memory, and trim values loaded from environment variables.
3. The model or route was retired or renamed. A name from an old article or saved snippet may no longer be available. Use the current model page and changelog as the source of truth.
4. The request mixes route formats. When a model offers multiple routes, use the documented top-level route field or the supported @route form, but do not send conflicting values.
5. Authentication failed before routing. A 401 means the API key is missing or invalid. A 403 means the key does not have permission. Fix those separately from the model field.

Fix steps

1. Open the current GPT Image 2 documentation or the relevant model page and copy the exact model name.
2. Keep modality suffixes that are part of the documented name. For GPT Image 2 text-to-image, use gpt-image-2/text-to-image.
3. Compare every field inside input with that model's parameter table. A valid model name can still return 400 INVALID_REQUEST when an input field is unsupported.
4. Strip whitespace at the call site. In Python, use model = os.environ["MODEL"].strip(); in Node.js, use model.trim().
5. If the model has multiple routes, pass the documented top-level route value and use the parameter shape for that route.
6. Log the full HTTP status and response body. Do not infer a key problem from a model validation error, or a model problem from a 401/403.

Verify with a minimal request

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "a small ceramic mug on a wooden table, soft window light",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

An HTTP 200 response with data.taskId means the task was accepted. Poll GET /v1/tasks/:id until data.status is success or fail, or configure a callback for production. For a 400, read the validation message and re-check the model page. For a 401 or 403, fix the key or its permissions.

Related

• GPT Image 2 model documentation
• Create Task API reference
• Authentication guide
• HiAPI models overview

FAQ

Should I strip /text-to-image from every model name? No. Model naming differs by family. Copy the fixed value from the current model documentation. For GPT Image 2 text-to-image, /text-to-image is part of the model name.

Does a model error mean my key is wrong? Not necessarily. Request validation and authentication are separate. A 401 means the key is missing or invalid; a 403 means it lacks permission. A 400 points to the request shape, model name, route, or input fields.

Can I normalize all model names in my client? Avoid inventing a normalization rule. Store and send the exact names published in the current model documentation.