Skip to content
HIPS
  • Earn with your GPU
  • Pricing
  • Docs
Sign inJoin early access
⌘K

Get started

  1. 01Developer hub
  2. 02Quickstart
  3. 03Migrate to HIPS

Guides

  1. 04HIPS SDK
  2. 05Import and run your model
  3. 06Model and task guides
    1. ATask guides
    2. BLanguage (chat)
    3. CClassification
    4. DImage
    5. EVideo
    6. FAudio
    7. GDocument processing
  4. 07Batch jobs
  5. 08Prompt caching
  6. 09Code with HIPS
  7. 10Coding-tool setup
    1. AHIPS Code
    2. BClaude Code
    3. CCodex
    4. DOpenCode
    5. EKilo
    6. FPi
    7. GQwen Code
    8. HCrush
    9. ICline
    10. JPrime Agent
    11. KAider
    12. LGoose
    13. MHermes Agent
    14. NGrok Build
    15. ODeepSeek Harness
    16. POther coding tools and editor integrations
  8. 11Command line
    1. AInstall and update
    2. BSign in
    3. CStatus and models
    4. DCoding agents
  9. 12Console
    1. AAccount
    2. BWorkspaces
    3. CAPI keys
    4. DSettings
    5. EUsage
    6. FModels
    7. GPlayground
    8. HDeployments
  10. 13Billing
  11. 14Provider setup
    1. AWhen it works
    2. BCommands
    3. CSettings
    4. DProvider Console
    5. EEarnings
    6. FCrash reports
    7. GData centers
  12. 15Semantic routing
  13. 16Guardrails
  14. 17Knowledge

Reference

  1. 18API reference
    1. AAuthentication
    2. BChat completions
    3. CResponses
    4. DMessages
    5. ECount tokens
    6. FModels
    7. GPrices API
    8. HTasks
    9. IEmbeddings and rerank
    10. JImages
    11. KJobs
    12. LUploads
    13. MFiles
    14. NBatches
    15. OWebhooks
    16. PVector stores
    17. QDeployments
    18. RRequirements and headers
    19. SErrors
    20. TUsage
    21. UVersioning
  2. 19Operating guidance
    1. ALimits
    2. BErrors
    3. CRetries and billing outcomes
    4. DIdempotency
    5. EStreaming
    6. FData handling
    7. GCompatibility matrix
  3. 20Changelog
Sheet indexAPI reference

Get started

  1. 01Developer hub
  2. 02Quickstart
  3. 03Migrate to HIPS

Guides

  1. 04HIPS SDK
  2. 05Import and run your model
  3. 06Model and task guides
    1. ATask guides
    2. BLanguage (chat)
    3. CClassification
    4. DImage
    5. EVideo
    6. FAudio
    7. GDocument processing
  4. 07Batch jobs
  5. 08Prompt caching
  6. 09Code with HIPS
  7. 10Coding-tool setup
    1. AHIPS Code
    2. BClaude Code
    3. CCodex
    4. DOpenCode
    5. EKilo
    6. FPi
    7. GQwen Code
    8. HCrush
    9. ICline
    10. JPrime Agent
    11. KAider
    12. LGoose
    13. MHermes Agent
    14. NGrok Build
    15. ODeepSeek Harness
    16. POther coding tools and editor integrations
  8. 11Command line
    1. AInstall and update
    2. BSign in
    3. CStatus and models
    4. DCoding agents
  9. 12Console
    1. AAccount
    2. BWorkspaces
    3. CAPI keys
    4. DSettings
    5. EUsage
    6. FModels
    7. GPlayground
    8. HDeployments
  10. 13Billing
  11. 14Provider setup
    1. AWhen it works
    2. BCommands
    3. CSettings
    4. DProvider Console
    5. EEarnings
    6. FCrash reports
    7. GData centers
  12. 15Semantic routing
  13. 16Guardrails
  14. 17Knowledge

Reference

  1. 18API reference
    1. AAuthentication
    2. BChat completions
    3. CResponses
    4. DMessages
    5. ECount tokens
    6. FModels
    7. GPrices API
    8. HTasks
    9. IEmbeddings and rerank
    10. JImages
    11. KJobs
    12. LUploads
    13. MFiles
    14. NBatches
    15. OWebhooks
    16. PVector stores
    17. QDeployments
    18. RRequirements and headers
    19. SErrors
    20. TUsage
    21. UVersioning
  2. 19Operating guidance
    1. ALimits
    2. BErrors
    3. CRetries and billing outcomes
    4. DIdempotency
    5. EStreaming
    6. FData handling
    7. GCompatibility matrix
  3. 20Changelog
18
  1. Docs/
  2. API reference/
  3. Images
(Detail J)
llms.txt

Images

On this sheet2 sections
  1. The answer
  2. Refusals

OpenAI's two image routes, front doors on the task API's image_generation and image_edit (decided 2026-11-04, the edit route 2026-11-12): each body is read in OpenAI's shape and served as the task it stands for, with the task route's key, limits, idempotency-key, requirement headers, quote, content checks and placement (Image generation and editing). Neither body takes a hips object: requirements ride as the x-hips-* headers. A route answers 400 type_not_served at model while no model of its type is served.

POST/v1/images/generationsserved

Image generation in OpenAI's JSON shape, billed per image at its size. Answers 400 type_not_served while no image generation model is served.

F
Fig. 1, sheet 18API reference

Request

00000000000000000000000000000000000000001{"model": "<catalog id>", "prompt": "A red apple on a wooden table, soft morning light", "n": 2, "size": "1024x1024", "output_format": "png"}
Request sample

Parts list: Generation fields

  1. 01
    modelRequired

    An image model's catalog id, alias or pinned id. A model of another task is a 400 task_mismatch.

  2. 02
    promptRequired

    A string, not empty, at most 64 KiB, with no NUL character.

  3. 03
    nAccepted

    The images to make, from 1 to the model's limit and never above 8; 1 when absent. A string of digits is read as the number.

  4. 04
    sizeAccepted

    <width>x<height> in pixels, such as 1024x1024, held to the model's bounds as width and height are on the task API; auto or absent, the model's own size. The size sets the price, and one the model is not offered at is a 400 invalid_value naming the sizes it is.

  5. 05
    output_formatAccepted

    png (the default, lossless), jpeg or webp (lossless).

  6. 06
    output_compressionAccepted with jpeg

    A jpeg output's quality, a whole number from 1 to 100, 75 when absent. With a png output, the default, or a webp output, which are lossless, a 400 unsupported_value; anything but a whole number a 400 invalid_type.

  7. 07
    response_formatAccepted as b64_json

    Images are answered inline; HIPS keeps no image to link to, so url is a 400 unsupported_value.

  8. 08
    userAccepted, not used

    A string. It changes neither the images nor the bill.

  9. 09
    streamAccepted as false

    true is a 400 unsupported_parameter: an image answer is never streamed.

  10. 10
    quality, style, background, moderation, partial_images, input_fidelityRejected, 400 unsupported_parameter

    OpenAI's fields that HIPS does not serve, named in the refusal.

  11. 11
    Any other nameRejected, 400 unknown_parameter

    Never ignored, even when sent as null. A field sent twice is a 400 invalid_value.

POST/v1/images/editsserved

Image editing in OpenAI's multipart shape, billed per image at its size. Answers 400 type_not_served while no image editing model is served.

A multipart/form-data body, its fields those of the generation route as form fields, beside the images as file parts. Anything else is a 400 invalid_value at body.

Parts list: Edit fields

  1. 01
    image, image[]Required

    The images to change, each a file part, at most 16 in a form and at most the model's number of input images. PNG, JPEG or WebP, told by their first bytes; an empty part is a 400 invalid_image. The input images' bounds of the task API hold (Input images).

  2. 02
    maskOn a model that inpaints

    One file part, the area to paint over. A model that takes no mask refuses it with a 400 unsupported_value; a second mask is a 400 invalid_value.

  3. 03
    model, prompt, n, size, output_format, output_compression, response_format, user, streamAs on the generation route

    Form fields, each sent once.

  4. 04
    Any other fieldRejected

    OpenAI's fields HIPS does not serve are a 400 unsupported_parameter, any other name a 400 unknown_parameter, a field sent twice a 400 invalid_value.

A body on either route is at most 3,358,720 bytes, the images within the 3,096,576 bytes one request carries to a GPU; a larger body is a 400 request_too_large before it is read whole, since an image request carries its images inline and takes no upload.

The answer

Answer

00000000000000000000000000000000000000001{2  "created": 1792663200,3  "data": [{"b64_json": "<base64>"}],4  "output_format": "png",5  "size": "1024x1024",6  "hips": {7    "withheld": [8      {"index": 1, "error": {"message": "HIPS's automated content checks withheld this image: ...", "type": "invalid_request_error", "param": null, "code": "image_withheld"}}9    ]10  }11}
Answer sample

Parts list: Fields

  1. 01
    created

    The answer's time, in seconds since 1970.

  2. 02
    data

    Each delivered image in order, as b64_json, marked as made with AI (The AI-generated mark).

  3. 03
    output_format, size

    The format and the size of every image of the answer.

  4. 04
    hips.withheld

    Only when the content checks withheld an image: each withheld image's index among the images asked and its error, whose message is the statement of reasons. A withheld image is not billed.

The answer carries the task route's headers: x-hips-cost-micros (the images delivered times the price at their size), x-hips-quote, x-hips-model, x-hips-pool and x-hips-request-id (Requirements and headers). There is no usage object.

An image answer's body must be read within 120 seconds of its head: a client reading slower than about 270 KB/s on a 32 MiB answer is cut, and the answer is not resent.

Refusals

A refusal is in the error envelope, and param names the field as these routes name it: n, size, prompt, image, image[0], mask, output_compression. The content checks' refusals, the 429 and 503 an image request can meet and what each costs are on Image generation and editing.

StatusTypeCodeSituationRetry
400invalid_request_errorinvalid_jsonThe body is not JSON, or not an objectNo
400invalid_request_errormissing_required_parameterA required field or header is absent; param names itNo
400invalid_request_errorinvalid_typeA field has the wrong JSON typeNo
400invalid_request_errorinvalid_valueA value is out of range or malformed: stop with more than 16 entries, a prompt_cache_key over 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, both max_tokens names with different valuesNo
400invalid_request_errorunknown_parameterA field the gateway does not know, at any depth; param names itNo
400invalid_request_errorunsupported_parameterA known field HIPS does not accept, or a feature the named model does not advertise in the pool the request resolves to; param names it and message names the modelNo
400invalid_request_errorunsupported_valuen other than 1, stream_options without stream, a message role, part, item or tool type not accepted, a hosted tool that is not servedNo
400invalid_request_errortype_not_servedPOST /v1/audio/transcriptions or /v1/audio/speech, or POST /v1/images/generations or /v1/images/edits while no model of the route's type is served: the message names the typeOnce the type is served
400invalid_request_errorinvalid_imageAn image part or input cannot be decoded, is of an unsupported type or over the pixel limitNo
400invalid_request_errorrequest_too_large, input_too_large, too_many_inputs, upload_too_largeA limit of the Limits pageNo
400invalid_request_errortask_mismatchtask is not the model's task, or the model is not an embedding model or a reranker on its routeNo
400invalid_request_errorrequirement_conflictTwo requirements that cannot both hold, a header and a hips field that differ, a pool the model is never offered in, community with an always-on deployment, a knowledge base whose requirements the request cannot meetNo
400invalid_request_errorinvalid_idempotency_key, idempotency_key_reused, idempotency_in_progressThe idempotency rulesThe last one, later
400invalid_request_errorcontent_refusedAn image request the content checks refused: its prompt or an input image asks for content the Acceptable Use Policy prohibits (param the prompt, inputs[0].text, for a generation, inputs for an edit; before any work), or every image made was withheld (param task). The message is the statement of reasons. Nothing chargedNo
400invalid_request_errorimage_withheldNot a request's answer: the error a withheld image carries in a task's results or in an image route's hips.withheld, beside the images delivered, its message the statement of reasons. A withheld image is not chargedNo
402insufficient_creditinsufficient_creditThe balance does not cover the request's maximum cost at the bound quoteAfter a top-up
402insufficient_creditbudget_exceededA budget guardrail of the workspace, the key or the person is at its limit with block; the error carries guardrail and resets_at (null for a budget that never resets). Never a payment challengeAfter resets_at, or once the limit is raised
403permission_errorpool_not_allowedA pool the workspace may not use for this model: one an access guardrail keeps out (named in the error), or a customer model's pool whose runtime-access conditions were not acceptedNo
403permission_errormodel_not_allowed, region_not_allowedA model, or a region requirement, that an access guardrail keeps out, the guardrail named in the error's guardrail memberNo
403permission_errorguardrail_unsupportedA content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, unchargedNo
404not_found_errormodel_not_foundUnknown catalog id, alias, pinned id or dep_; another workspace's dep_; a name starting with hips-router that is not one of the four routersNo
404not_found_errorresult_expiredA task, embeddings or rerank request retried with its idempotency-key after the first completed: no answer is kept, and the message names the first request's req_ id. It ran and was billed onceNo
429rate_limit_errorrate_limit_exceededA rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_search; Retry-AfterYes, after Retry-After
503overloaded_errorno_capacityNo eligible worker under the request's requirements, in any pool the requirements allow; Retry-After. The message says what those pools can do now: a GPU that fits the model takes it when free or loads it when asked, which can take minutes or longer; or nothing can serve it, and a retry sooner than the given delay gets the same answerYes, after the given delay
503overloaded_errorpool_unavailableThe named pool has no eligible supply for this model now and fallback is off; the other pool may have; Retry-AfterYes, or with fallback
503overloaded_erroroverloadedEligible workers exist and every one is saturated, or the queue is full; Retry-AfterYes
503overloaded_errorcontent_check_unavailableThe content checks of an image request could not run (the decision service failed or did not answer in time), and HIPS sends no image request unchecked; Retry-After; unchargedYes, after Retry-After
500api_errorinternal_errorA fault in HIPS. Nothing billedOnce
500api_errorattempt_failedEvery attempt failed for a reason that is not the client's and retries are exhausted. Nothing billedOnce
500api_errordeadline_exceededThe request's own time bound ended it; x-should-retry: false. Nothing billedNot unchanged
  • Status
    400
    Type
    invalid_request_error
    Code
    invalid_json
    Situation
    The body is not JSON, or not an object
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    missing_required_parameter
    Situation
    A required field or header is absent; param names it
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    invalid_type
    Situation
    A field has the wrong JSON type
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    invalid_value
    Situation
    A value is out of range or malformed: stop with more than 16 entries, a prompt_cache_key over 512 characters, a string holding a lone surrogate escape, a router name with an empty or unknown suffix, both max_tokens names with different values
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    unknown_parameter
    Situation
    A field the gateway does not know, at any depth; param names it
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    unsupported_parameter
    Situation
    A known field HIPS does not accept, or a feature the named model does not advertise in the pool the request resolves to; param names it and message names the model
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    unsupported_value
    Situation
    n other than 1, stream_options without stream, a message role, part, item or tool type not accepted, a hosted tool that is not served
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    type_not_served
    Situation
    POST /v1/audio/transcriptions or /v1/audio/speech, or POST /v1/images/generations or /v1/images/edits while no model of the route's type is served: the message names the type
    Retry
    Once the type is served
  • Status
    400
    Type
    invalid_request_error
    Code
    invalid_image
    Situation
    An image part or input cannot be decoded, is of an unsupported type or over the pixel limit
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    request_too_large, input_too_large, too_many_inputs, upload_too_large
    Situation
    A limit of the Limits page
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    task_mismatch
    Situation
    task is not the model's task, or the model is not an embedding model or a reranker on its route
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    requirement_conflict
    Situation
    Two requirements that cannot both hold, a header and a hips field that differ, a pool the model is never offered in, community with an always-on deployment, a knowledge base whose requirements the request cannot meet
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    invalid_idempotency_key, idempotency_key_reused, idempotency_in_progress
    Situation
    The idempotency rules
    Retry
    The last one, later
  • Status
    400
    Type
    invalid_request_error
    Code
    content_refused
    Situation
    An image request the content checks refused: its prompt or an input image asks for content the Acceptable Use Policy prohibits (param the prompt, inputs[0].text, for a generation, inputs for an edit; before any work), or every image made was withheld (param task). The message is the statement of reasons. Nothing charged
    Retry
    No
  • Status
    400
    Type
    invalid_request_error
    Code
    image_withheld
    Situation
    Not a request's answer: the error a withheld image carries in a task's results or in an image route's hips.withheld, beside the images delivered, its message the statement of reasons. A withheld image is not charged
    Retry
    No
  • Status
    402
    Type
    insufficient_credit
    Code
    insufficient_credit
    Situation
    The balance does not cover the request's maximum cost at the bound quote
    Retry
    After a top-up
  • Status
    402
    Type
    insufficient_credit
    Code
    budget_exceeded
    Situation
    A budget guardrail of the workspace, the key or the person is at its limit with block; the error carries guardrail and resets_at (null for a budget that never resets). Never a payment challenge
    Retry
    After resets_at, or once the limit is raised
  • Status
    403
    Type
    permission_error
    Code
    pool_not_allowed
    Situation
    A pool the workspace may not use for this model: one an access guardrail keeps out (named in the error), or a customer model's pool whose runtime-access conditions were not accepted
    Retry
    No
  • Status
    403
    Type
    permission_error
    Code
    model_not_allowed, region_not_allowed
    Situation
    A model, or a region requirement, that an access guardrail keeps out, the guardrail named in the error's guardrail member
    Retry
    No
  • Status
    403
    Type
    permission_error
    Code
    guardrail_unsupported
    Situation
    A content moderation guardrail applies to text it does not scan yet: a batch, or a task request with text; the guardrail named, uncharged
    Retry
    No
  • Status
    404
    Type
    not_found_error
    Code
    model_not_found
    Situation
    Unknown catalog id, alias, pinned id or dep_; another workspace's dep_; a name starting with hips-router that is not one of the four routers
    Retry
    No
  • Status
    404
    Type
    not_found_error
    Code
    result_expired
    Situation
    A task, embeddings or rerank request retried with its idempotency-key after the first completed: no answer is kept, and the message names the first request's req_ id. It ran and was billed once
    Retry
    No
  • Status
    429
    Type
    rate_limit_error
    Code
    rate_limit_exceeded
    Situation
    A rate limit; param is requests, tokens, uploads, batches (batches created per hour) or knowledge_search; Retry-After
    Retry
    Yes, after Retry-After
  • Status
    503
    Type
    overloaded_error
    Code
    no_capacity
    Situation
    No eligible worker under the request's requirements, in any pool the requirements allow; Retry-After. The message says what those pools can do now: a GPU that fits the model takes it when free or loads it when asked, which can take minutes or longer; or nothing can serve it, and a retry sooner than the given delay gets the same answer
    Retry
    Yes, after the given delay
  • Status
    503
    Type
    overloaded_error
    Code
    pool_unavailable
    Situation
    The named pool has no eligible supply for this model now and fallback is off; the other pool may have; Retry-After
    Retry
    Yes, or with fallback
  • Status
    503
    Type
    overloaded_error
    Code
    overloaded
    Situation
    Eligible workers exist and every one is saturated, or the queue is full; Retry-After
    Retry
    Yes
  • Status
    503
    Type
    overloaded_error
    Code
    content_check_unavailable
    Situation
    The content checks of an image request could not run (the decision service failed or did not answer in time), and HIPS sends no image request unchecked; Retry-After; uncharged
    Retry
    Yes, after Retry-After
  • Status
    500
    Type
    api_error
    Code
    internal_error
    Situation
    A fault in HIPS. Nothing billed
    Retry
    Once
  • Status
    500
    Type
    api_error
    Code
    attempt_failed
    Situation
    Every attempt failed for a reason that is not the client's and retries are exhausted. Nothing billed
    Retry
    Once
  • Status
    500
    Type
    api_error
    Code
    deadline_exceeded
    Situation
    The request's own time bound ended it; x-should-retry: false. Nothing billed
    Retry
    Not unchanged

Related sheets

  • Image generation and editing
  • Tasks
  • Usage
Previous sheetEmbeddings and rerank
Next sheetJobs
Sheet
18 of 20
Detail
J
Updated
2026-11-16
Sign in to the Console

On this sheet

  1. The answer
  2. Refusals

Product

  • Inference
  • Models
  • Deploy your model
  • Always-on GPU capacity
  • How it works
  • Use cases
  • Pricing

Developer

  • Docs
  • Quickstart
  • Migrate to HIPS
  • HIPS SDK
  • Batch jobs
  • API reference

Provider

  • Earn with your GPU
  • Register GPU interest
  • Download for Mac
  • Download for Windows
  • Download for Linux

Resource

  • Security and Data
  • Resources
  • llms.txt

Compare

  • OpenRouter alternatives
  • Together AI alternatives
  • Groq alternatives
  • All comparisons

Company

  • About
  • Contact
  • Affiliate program
  • HIPS Payments

Legal

  • Legal
  • Consumer Health Data Privacy Policy
  • Report content
  • Cookie preferences

Support

  • Contact HIPS
  • Looking for payments support?

HIPS. AI inference for builders.

hips.com

Hyperscale Inference Processing Systems OÜ