> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hilinkup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Edit images

> Edit an existing image with POST /v1/images/edits.

Edit an existing image with a text prompt. Submit the request as `multipart/form-data` with the source file in the `image` field.

<Info>
  The snippets below are complete requests. Set `HILINKUP_API_KEY` to your real key first, and replace `model` with an image model ID returned by `GET /v1/models` that supports editing.
</Info>

## Request parameters

<ParamField body="model" type="string" required>
  An image model ID that supports editing. Not every generation model supports edits.
</ParamField>

<ParamField body="prompt" type="string" required>
  A text description of the requested change. The more specific the prompt, the more reliably the source image is preserved.
</ParamField>

<ParamField body="image" type="file" required>
  The source image file. Supported formats and size limits depend on the model.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Number of images to generate. Some models only support `1`.
</ParamField>

<ParamField body="size" type="string">
  Output image size. Valid values depend on the model.
</ParamField>

## Request examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.hilinkup.com/v1/images/edits \
    -H "Authorization: Bearer $HILINKUP_API_KEY" \
    -F "model=aliyun/qwen-image-3.0" \
    -F "prompt=Add a red scarf to the cat, keep the background and composition unchanged." \
    -F "image=@input.png"
  ```

  ```python Python theme={null}
  import os

  import requests

  API_KEY = os.environ["HILINKUP_API_KEY"]
  BASE_URL = "https://api.hilinkup.com/v1"

  with open("input.png", "rb") as image:
      response = requests.post(
          f"{BASE_URL}/images/edits",
          headers={"Authorization": f"Bearer {API_KEY}"},
          data={
              "model": "aliyun/qwen-image-3.0",
              "prompt": "Add a red scarf to the cat, keep the background and composition unchanged.",
          },
          files={"image": ("input.png", image, "image/png")},
          timeout=300,
      )
  response.raise_for_status()

  result = response.json()
  print(result["data"][0]["url"])
  ```

  ```javascript Node.js theme={null}
  import { openAsBlob } from "node:fs";

  const apiKey = process.env.HILINKUP_API_KEY;

  const form = new FormData();
  form.append("model", "aliyun/qwen-image-3.0");
  form.append("prompt", "Add a red scarf to the cat, keep the background and composition unchanged.");
  form.append("image", await openAsBlob("input.png"), "input.png");

  const response = await fetch("https://api.hilinkup.com/v1/images/edits", {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}` },
    body: form,
  });

  if (!response.ok) {
    throw new Error(`Request failed ${response.status}: ${await response.text()}`);
  }

  const result = await response.json();
  console.log(result.data[0].url);
  ```
</CodeGroup>

## Response

<ResponseExample>
  ```json theme={null}
  {
    "created": 1782972000,
    "data": [
      {
        "url": "https://api.hilinkup.com/v1/images/files/img_2c7d91f0.png"
      }
    ]
  }
  ```
</ResponseExample>

<ResponseField name="created" type="integer">
  Unix timestamp of the generation result.
</ResponseField>

<ResponseField name="data" type="array">
  List of image results. Each item contains `url` or `b64_json`.
</ResponseField>

<Note>
  The response may return a temporary URL or Base64 data, usually in a `b64_json` field. Download and store the result before the URL expires.
</Note>

## Saving the result

```python theme={null}
import requests

image_url = result["data"][0]["url"]

image = requests.get(image_url, timeout=60)
image.raise_for_status()

with open("output.png", "wb") as file:
    file.write(image.content)
```

<Warning>
  The model IDs, response fields, and URLs in these examples illustrate the request format only. Confirm in the model catalog or console that your account can access the editing model, and check its input image limits and output sizes.
</Warning>

<Note>
  Stating what must stay unchanged (background, composition, subject features) usually reduces unintended edits, but how closely a model follows this varies.
</Note>

## Next steps

To create a new image from text only, use [Generate images](/en/api-reference/images).


## OpenAPI

````yaml openapi.json POST /v1/images/edits
openapi: 3.0.3
info:
  title: HiLinkup API
  description: >-
    HiLinkup 统一模型 API。兼容 OpenAI Responses、Chat Completions、Claude
    Messages、Gemini generateContent 协议。
  version: 1.0.0
servers:
  - url: https://api.hilinkup.com
security:
  - bearerAuth: []
paths:
  /v1/images/edits:
    post:
      summary: 编辑图像
      description: 基于已有图像和文本提示生成修改后的图像。请求使用 multipart/form-data 提交。
      operationId: editImage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - model
                - prompt
                - image
              properties:
                model:
                  type: string
                  description: 支持图像编辑的模型 ID。并非所有图像生成模型都支持编辑。
                prompt:
                  type: string
                  description: 描述修改目标的文本提示。
                image:
                  type: string
                  format: binary
                  description: 要编辑的原图文件。支持的格式和大小由模型决定。
                'n':
                  type: integer
                  default: 1
                  description: 要生成的图像数量。部分模型只支持 1。
                size:
                  type: string
                  description: 输出图像尺寸。可用值由模型决定。
            encoding:
              image:
                contentType: image/png, image/jpeg, image/webp
      responses:
        '200':
          description: 图像编辑结果
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageUrl'
              example:
                created: 1782972000
                data:
                  - url: https://api.hilinkup.com/v1/images/files/img_2c7d91f0.png
components:
  schemas:
    ImageUrl:
      type: object
      properties:
        created:
          type: integer
          description: 生成结果的 Unix 时间戳。
        data:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                description: 生成图像的临时 URL。
              b64_json:
                type: string
                description: Base64 编码的图像数据，取决于模型的返回格式。
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: '在控制台创建的 API Key，格式为 `Authorization: Bearer HILINKUP_API_KEY`。'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.