Edit Image
edit_imageEdit or transform existing images through POST /v1/tasks with the REST request body { model, route?, input, callback?, storage? }. Pass the model's published fields inside input, or use the convenience top-level prompt/aspect_ratio/resolution/background/output_format/image_urls fields. Default model: gpt-image-2.5-sunburst/image-to-image (1-16 source images via image_urls). Any live image model that publishes a reference-image field also works (for example nano-banana-2, nano-banana-pro or flux-2-klein-4b/image-to-image); source images passed through the top-level aliases are mapped onto that model's published field. route, callback and storage work exactly as in POST /v1/tasks. A model or route that is not in the public catalog is submitted verbatim for the backend to authorize. Asynchronous: it only submits the task and returns a task_id immediately, never the result. To retry safely after a timeout or dropped connection, pass an idempotency_key and reuse it on the retry; HiAPI then returns the original task instead of charging twice. Call get_task_status with that task_id to fetch the result.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "edit_image"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| input | No | The model's input object, exactly as in POST /v1/tasks. It may contain any field the model publishes — call get_model_schema for the authoritative list. Values here win over the convenience top-level fields and over the legacy params alias. | |
| model | No | Editing model: gpt-image-2.5-sunburst/image-to-image (default), or any live image model with a published reference-image field (nano-banana-2, nano-banana-pro, flux-2-klein-4b/image-to-image, ...). | |
| route | No | REST top-level model route, for example pro, ext or beta. Sent next to model (never concatenated). The catalog is consulted as model@route first, then model; a route that is not public is still submitted for the backend to authorize. | |
| prompt | No | Description of the desired edit. Becomes input.prompt in the REST body. | |
| storage | No | REST top-level storage tier: temp (default, kept about 7 days) or persistent (kept long-term, billed by size). Insufficient balance silently downgrades to temp. | |
| callback | No | REST top-level callback: HiAPI POSTs to url when the task reaches a terminal state (success or failure), so you can skip polling. url is required; when defaults to final. | |
| background | No | REST field background for gpt-image-2.5-sunburst: transparent, opaque or auto. Supported only at 1K resolution; omit for 2K/4K. | |
| image_urls | No | REST field image_urls: source image URLs or data:image/... URIs (up to 16 for gpt-image-2.5-sunburst, up to 8 for nano-banana models). | |
| resolution | No | REST field resolution: 1K, 2K, 4K. | |
| aspect_ratio | No | REST field aspect_ratio. Examples: auto, 1:1, 16:9, 9:16, 4:3, 3:4. gpt-image-2.5-sunburst also accepts 3:2, 2:3, 5:4, 4:5, 21:9, 27:16, 16:27, 9:8, 8:9. | |
| output_format | No | REST field output_format for nano-banana-2 / nano-banana-pro: png or jpg. gpt-image-2.5-sunburst has no output_format field. | |
| idempotency_key | No | Optional key for this job (max 255 bytes), e.g. a fresh UUID. If this call times out or the connection drops, retry with the same key: HiAPI returns the original task instead of charging a second one. The key is kept about 24 hours and replays even a failed task, so use a new key for every new generation. Without a key every call creates and charges a new task. |