Image generation and editing
Two tasks. image_generation makes new images from a text prompt. image_edit changes one or more of your images as an instruction says, such as "make the t-shirt green". Both are synchronous: one request, and its answer carries the images inline in base64. Send them on the task API, POST /v1/tasks, or on OpenAI's image routes, POST /v1/images/generations and POST /v1/images/edits, designed to follow OpenAI's image API so its clients work with your HIPS key and base URL (Images). Each image is billed at a fixed price for its size, and every image carries a machine-readable mark that it was made with AI.
| Task | Inputs | What it does |
|---|---|---|
image_generation | A text prompt; optionally a negative prompt | New images from the prompt |
image_edit | One or more images and an instruction; a mask, on a model that inpaints | Your images changed as the instruction says |
- Task
image_generation- Inputs
- A text prompt; optionally a negative prompt
- What it does
- New images from the prompt
- Task
image_edit- Inputs
- One or more images and an instruction; a mask, on a model that inpaints
- What it does
- Your images changed as the instruction says
Note
A route of an image task answers 400 type_not_served at model while no model of its type is served. The image models HIPS serves are listed in GET /v1/models, each with the task it serves, and on Models with the price per image at each size it is offered at.
On the task API the prompt is the task's one text input, not an option: not empty, at most 64 KiB, with no NUL character. A second text input is a 400 invalid_value. The options below are in options, and the request requirements in the hips object or the x-hips-* headers, as on every task (Tasks).
# HIPS_BASE_URL is https://ai.hips.com/v1curl "$HIPS_BASE_URL/tasks" \ -H "Authorization: Bearer $HIPS_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"model\":\"$HIPS_MODEL\",\"task\":\"image_generation\",\"inputs\":[{\"id\":\"p\",\"type\":\"text\",\"text\":\"A red apple on a wooden table, soft morning light\"}],\"options\":{\"width\":1024,\"height\":1024,\"count\":2}}"An edit adds the image to change as an image input:
Edit request
{ "model": "<catalog id>", "task": "image_edit", "inputs": [ {"id": "p", "type": "text", "text": "Make the t-shirt green"}, {"id": "photo", "type": "image", "data": "<base64 of a PNG, JPEG or WebP>"} ], "options": {"output_format": "jpeg", "output_quality": 90, "seed": 42}}Parts list: options
width, heightwhole numbersOptionalThe size in pixels; absent, the model's own size. At least the model's smallest side and at most its largest, never above 8,192; each a multiple of 8 and of the model's own alignment; together at most the model's largest image in pixels, or 4,194,304 (2048 by 2048) where the model states none. The size sets the price (Usage unit). Out of bounds is a 400
invalid_valuenaming the bound.countwhole numberOptionalThe images to make, from 1 to the model's limit and never above 8; 1 when absent.
stepswhole numberOptionalSampling steps, from 1 to the model's limit and never above 200; the model's own when absent. Steps do not change the price: the model's limit bounds the work a price covers.
seedwhole numberOptionalFrom 0 to 9,223,372,036,854,775,807. Absent, HIPS draws one, and the answer's
seedsays which. The images of a request are made withseed,seed + 1and so on, as if in one run. A seed is no promise of the same pixels on another GPU.negative_promptstringOptionalWhat the image should not show. At most 64 KiB, with no NUL character.
samplerstringOptionalThe model's own when absent. One of
euler,euler_a,heun,dpm2,dpm++2s_a,dpm++2m,dpm++2mv2,ipndm,ipndm_v,lcm,ddim_trailing,tcd,res_multistep,res_2s,er_sde,euler_cfg_pp,euler_a_cfg_pp,euler_ge,dpm++2m_sde,dpm++2m_sde_bt,lms.schedulerstringOptionalThe model's own when absent. One of
discrete,karras,exponential,ays,gits,sgm_uniform,simple,smoothstep,kl_optimal,lcm,bong_tangent,ltx2,logit_normal,flux2,flux,beta,llada_image.cfg_scale, guidancenumbersWhere the model takes themThe classifier-free guidance scale and the distilled guidance, from 0 to 100, the model's own when absent. On a model that does not take the setting, a 400
unsupported_parameternaming it.output_formatpng,jpeg,webpOptionalpngwhen absent. PNG and WebP are lossless; a JPEG is encoded by HIPS from the GPU's lossless image.output_qualitywhole numberJPEG onlyA JPEG's quality from 1 to 100, 75 when absent. A PNG or a WebP takes 0 or nothing: any other value is a 400
unsupported_value.Any other optionRejected, 400 unknown_parameterNever ignored.
- Each image is an input with
type: "image"and its bytes inline asdata, base64 with or without padding. Anupload_idis a 400unsupported_value: image tasks take their images inline. rolesays what the image is to the edit:reference(the default), an image to change or to take from, ormask, the area to paint over, on a model that inpaints. An edit takes at least one reference image (400missing_required_parameter), at most one mask (400invalid_value), and at most the model's number of input images, the mask counted (400too_many_inputs). A mask sent to a model that takes none is a 400unsupported_valueat the input'srole.- PNG, JPEG or WebP, told by the image's first bytes, never by a name or a declared type. Each is at most 8,192 pixels on a side and 33,554,432 pixels, read from its header before anything decodes it; anything else is a 400
invalid_imagenaming the input. - All the images of one request together are at most 3,096,576 bytes, since they travel to the GPU in one message; more is a 400
input_too_large. Send smaller or fewer images. - Their metadata is removed before an image reaches a GPU or the content checks: EXIF (a GPS position, a camera's serial number, an owner's name), XMP, color profiles, comments, thumbnails and text. No pixel is changed.
POST /v1/images/generations takes OpenAI's JSON body and POST /v1/images/edits its multipart form, designed to follow OpenAI's image API with the HIPS key and base URL; the compatibility matrix records each client once it is tested. Each is served as the task it stands for, with every rule on this page. They take model, prompt, n, size (<width>x<height>, or auto for the model's own), output_format and output_compression, a jpeg output's quality from 1 to 100; the edit route the images as image or image[] files and a mask file. They take no seed, steps, negative prompt or sampler: use the task API for those. Every field HIPS does not serve is refused with a 400 naming it, never ignored (Images).
import base64import os from openai import OpenAI client = OpenAI( api_key=os.environ["HIPS_API_KEY"], base_url=os.environ["HIPS_BASE_URL"], # https://ai.hips.com/v1) made = client.images.generate( model=os.environ["HIPS_MODEL"], prompt="A red apple on a wooden table, soft morning light", size="1024x1024",)with open("apple.png", "wb") as f: f.write(base64.b64decode(made.data[0].b64_json)) edited = client.images.edit( model=os.environ["HIPS_MODEL"], image=open("photo.png", "rb"), prompt="Make the t-shirt green",)with open("photo-green.png", "wb") as f: f.write(base64.b64decode(edited.data[0].b64_json))image: a fixed price per output image at each size the model is offered at, the same in both pools. Steps, the seed and the model's settings do not change it.- The quote is bound when the request is accepted: the images asked times the price at their size. That maximum is held against your balance first, a 402
insufficient_creditwhen it does not cover it, and a budget guardrail counts it like any request. - The bill is the images delivered times that price, in
x-hips-cost-micros. An image the content checks withhold is not billed, and a request that delivers no image is billed nothing. - An image request is billed for the images that were made, even if the client left before reading them, and if the client left before the output check finished, that includes any images the check would have withheld; a retry with the same idempotency key is then refused (result_expired, naming the first request), never run or billed again; a request the client leaves before any image is made is not charged.
- A size the model allows and no price covers is a 400
invalid_valuewhose message names the sizes the model is offered at (options.widthon the task API,sizeon OpenAI's routes). - On the task API,
usage.unitscounts the images asked andusage.billed_unitsthe images billed. OpenAI's routes answer nousage.
The task API answers one entry in results per image asked, in order, each with input the prompt's id and its index: the image's media_type, width, height and data in base64, or the error of an image the content checks withheld. The answer's seed is the one the images were made with.
Answer
{ "object": "task", "id": "job_...", "model": "<pinned id>", "task": "image_generation", "results": [ {"input": "p", "index": 0, "media_type": "image/png", "width": 1024, "height": 1024, "data": "<base64>"}, {"input": "p", "index": 1, "error": {"message": "HIPS's automated content checks withheld this image: ...", "type": "invalid_request_error", "param": null, "code": "image_withheld"}} ], "seed": 1234567, "usage": {"units": 2, "unit": "image", "billed_units": 1}}OpenAI's routes answer created, data with each delivered image's b64_json in order, output_format and size. A withheld image is left out of data, and the answer gains a hips object whose withheld names its index among the images asked, with its error:
Answer on OpenAI's routes
{ "created": 1792663200, "data": [{"b64_json": "<base64>"}], "output_format": "png", "size": "1024x1024", "hips": { "withheld": [ {"index": 1, "error": {"message": "HIPS's automated content checks withheld this image: ...", "type": "invalid_request_error", "param": null, "code": "image_withheld"}} ] }}- Images are answered inline alone. HIPS keeps no image after its answer, so there is no URL to fetch one from later: save what you need from the answer.
- Every image is 8-bit RGB, with no transparency, and carries the AI-generated mark below and no other metadata.
- A request whose images are made on more than one GPU, which HIPS does when one GPU's answer cannot carry them all, delivers all of them or none: if one part fails, nothing is delivered and nothing is billed.
While the checks are on, as they are by default, every image request is checked twice. Its prompt, with an edit's input images, is checked before any GPU works on it, and every image made is checked before it reaches you. The checks look for the content the Acceptable Use Policy prohibits in Sections 5.2 to 5.4: sexual content involving a minor, intimate imagery of an identifiable real person made or changed without their consent, and sexually explicit content. A decision service outside HIPS judges each check. The checks add nothing to the bill.
| When | What you get | Billed |
|---|---|---|
| The prompt or an input image is refused | 400 content_refused before any GPU works on it: at the prompt, inputs[0].text (prompt on OpenAI's routes), for a generation; at inputs (image on the edit route) for an edit, whose prompt and images are judged together | Nothing |
| An image made is withheld | The other images, and the withheld one's image_withheld error in its results entry, or in hips.withheld on OpenAI's routes | The images delivered |
| Every image made is withheld | 400 content_refused at task | Nothing |
| The check cannot run (the decision service failed or did not answer in time) | 503 content_check_unavailable with Retry-After: HIPS sends no image request unchecked | Nothing |
| The day's content checks are used up, HIPS's whole day's or the workspace's share of it | 429 rate_limit_exceeded with param checks, and Retry-After until they renew at midnight UTC | Nothing |
| The request requires a region | 400 requirement_conflict before any work, while the checks are on: the decision service is outside every region's processing, and a request that requires a region is processed only in its region | Nothing |
- When
- The prompt or an input image is refused
- What you get
- 400
content_refusedbefore any GPU works on it: at the prompt,inputs[0].text(prompton OpenAI's routes), for a generation; atinputs(imageon the edit route) for an edit, whose prompt and images are judged together - Billed
- Nothing
- When
- An image made is withheld
- What you get
- The other images, and the withheld one's
image_withhelderror in itsresultsentry, or inhips.withheldon OpenAI's routes - Billed
- The images delivered
- When
- Every image made is withheld
- What you get
- 400
content_refusedattask - Billed
- Nothing
- When
- The check cannot run (the decision service failed or did not answer in time)
- What you get
- 503
content_check_unavailablewithRetry-After: HIPS sends no image request unchecked - Billed
- Nothing
- When
- The day's content checks are used up, HIPS's whole day's or the workspace's share of it
- What you get
- 429
rate_limit_exceededwithparamchecks, andRetry-Afteruntil they renew at midnight UTC - Billed
- Nothing
- When
- The request requires a region
- What you get
- 400
requirement_conflictbefore any work, while the checks are on: the decision service is outside every region's processing, and a request that requires a region is processed only in its region - Billed
- Nothing
The message of a refusal and of a withheld image is the statement of reasons the Acceptable Use Policy gives in Section 13.5. A withheld image's reads: "HIPS's automated content checks withheld this image: it appears to show content the Acceptable Use Policy prohibits (Sections 5.2 to 5.4 and 11.10). This message is the statement of reasons (Section 13.5). It was not charged." HIPS records each refusal against the workspace with its reason, never the prompt or an image, to enforce the policy.
The checks are on by default. An owner or admin can turn them off for the workspace's image requests in Workspace settings. A model whose license requires content filtering or a review of its outputs keeps its checks on whatever the workspace sets, and the setting names those models beside the switch. Whatever any setting says, every image carries the mark below.
Every image HIPS answers carries a machine-readable mark that it was made with AI: the IPTC digital source type trainedAlgorithmicMedia for a generated image and compositeWithTrainedAlgorithmicMedia for an edit, as Iptc4xmpExt:DigitalSourceType in an XMP packet. A PNG carries it in an iTXt chunk named XML:com.adobe.xmp, a JPEG in an APP1 segment and a WebP in an XMP chunk. Writing it changes no pixel. The image carries no other metadata: not the prompt, the seed or the settings.
The Acceptable Use Policy (Section 6.3) asks you not to remove, alter or obscure it, and not to present an image as made by a person where the law requires its artificial origin to be disclosed.
- "HIPS never trains on, retains or logs your prompt data." A prompt and its images are held in memory for the request alone, on the gateway and on the GPU that serves it, and no image is kept after the answer (Data handling).
- An input image's metadata is removed before it reaches a GPU or the content checks, and no pixel is changed.
- The content checks send the prompt and the images to the decision service outside HIPS for the one check, after their metadata is removed.
- A refusal's record names the workspace and the reason, never the prompt or an image.
- An attempt interrupted because its GPU's owner came back, the provider app drained, or the connection or the GPU was lost runs again on another GPU, and you get its answer. An attempt that was canceled is never run again.
- 503
overloadedwithRetry-Afterwhen the gateway is at its bound for image requests, or the memory it gives image work is held by others; 503no_capacityorpool_unavailablewhen no GPU can serve the model under the request's requirements. Retry after the given delay. - 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.
- A request the GPUs serving the model cannot make now, such as a size larger than they make, is a 400 naming the field, and nothing is billed. A request that would take more of the gateway's memory than one request may hold is a 400
invalid_value: atoptions.count(non OpenAI's routes), naming how many images of that size it can make, or atoptions.width(size) when one image is too large, with a smaller size or a PNG to ask for, or atinputswhen an edit's input images are what does not fit, with smaller input images to send. - 500
attempt_failedwhen every attempt failed, and 500deadline_exceededwhen the request's own time bound ended it. Nothing is billed. - Guardrails: budgets and model and pool access apply to image requests as to every request. A content moderation guardrail does not scan a task's text yet, so an image request it applies to is refused 403
guardrail_unsupported, never sent unchecked (Guardrails).
idempotency-key is taken on POST /v1/tasks and on both image routes. HIPS keeps no answer for it: a retry with a key whose first request completed is refused 404 result_expired, its message naming the first request's req_ id, and nothing runs or is billed again. Keep the images from the first answer. The same key while the first request runs is a 400 idempotency_in_progress, and with another body a 400 idempotency_key_reused (Idempotency).
POST /v1/jobs: image requests are synchronous, and the job routes are not built yet.- Input images by reference, as an
upload_idor a URL: images go inline in the request. - A URL in the answer (
response_format: "url"), streaming and partial images. - OpenAI's
quality,style,background,moderationandinput_fidelity, andoutput_compressionfor a lossless output. - LoRA adapters, ControlNet, IP-Adapter, upscaling and face detailing, and a model split across several GPUs. Models that take a person's face to keep their identity are not offered.
- Importing your own image model.
Related sheets
- Sheet
- 06 of 20
- Detail
- D
- Updated
- 2026-11-16