图片编辑:根据指令编辑参考图或融合多图
curl --request POST \
--url https://api.apiyi.com/v1/images/edits \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form model=grok-imagine-image \
--form 'prompt=Change the scarf color to bright RED. Keep everything else exactly the same.' \
--form image='@example-file'import requests
url = "https://api.apiyi.com/v1/images/edits"
files = { "image": ("example-file", open("example-file", "rb")) }
payload = {
"model": "grok-imagine-image",
"prompt": "Change the scarf color to bright RED. Keep everything else exactly the same."
}
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('model', 'grok-imagine-image');
form.append('prompt', 'Change the scarf color to bright RED. Keep everything else exactly the same.');
form.append('image', '<string>');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.apiyi.com/v1/images/edits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.apiyi.com/v1/images/edits",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngrok-imagine-image\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the scarf color to bright RED. Keep everything else exactly the same.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.apiyi.com/v1/images/edits"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngrok-imagine-image\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the scarf color to bright RED. Keep everything else exactly the same.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/edits")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngrok-imagine-image\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the scarf color to bright RED. Keep everything else exactly the same.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.apiyi.com/v1/images/edits")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngrok-imagine-image\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the scarf color to bright RED. Keep everything else exactly the same.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"created": 0,
"data": [
{
"url": "https://apac.ossforai.com/2026/08/12/09b026d5-3492-4678-907c-e25972e6c914.jpg",
"b64_json": "<string>"
}
],
"usage": {
"prompt_tokens": 1000,
"total_tokens": 1000
}
}Grok Imagine 2 生图/编辑
图片编辑 API 参考
Grok Imagine 2 图片编辑 API 参考与在线调试 — 上传参考图(1-3 张)+ 指令进行改图或多图融合,必须使用 multipart/form-data
POST
/
v1
/
images
/
edits
图片编辑:根据指令编辑参考图或融合多图
curl --request POST \
--url https://api.apiyi.com/v1/images/edits \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form model=grok-imagine-image \
--form 'prompt=Change the scarf color to bright RED. Keep everything else exactly the same.' \
--form image='@example-file'import requests
url = "https://api.apiyi.com/v1/images/edits"
files = { "image": ("example-file", open("example-file", "rb")) }
payload = {
"model": "grok-imagine-image",
"prompt": "Change the scarf color to bright RED. Keep everything else exactly the same."
}
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('model', 'grok-imagine-image');
form.append('prompt', 'Change the scarf color to bright RED. Keep everything else exactly the same.');
form.append('image', '<string>');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.apiyi.com/v1/images/edits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.apiyi.com/v1/images/edits",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngrok-imagine-image\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the scarf color to bright RED. Keep everything else exactly the same.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: multipart/form-data"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.apiyi.com/v1/images/edits"
payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngrok-imagine-image\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the scarf color to bright RED. Keep everything else exactly the same.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/edits")
.header("Authorization", "Bearer <token>")
.body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngrok-imagine-image\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the scarf color to bright RED. Keep everything else exactly the same.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.apiyi.com/v1/images/edits")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngrok-imagine-image\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the scarf color to bright RED. Keep everything else exactly the same.\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"created": 0,
"data": [
{
"url": "https://apac.ossforai.com/2026/08/12/09b026d5-3492-4678-907c-e25972e6c914.jpg",
"b64_json": "<string>"
}
],
"usage": {
"prompt_tokens": 1000,
"total_tokens": 1000
}
}右侧的交互式 Playground 支持直接上传本地图片。请在 Authorization 中填入你的 API Key(格式:
Bearer sk-xxx),选择 image 文件并填入 prompt、model 后一键发送即可。🔴 本接口必须使用 如果你是照着 xAI / 上游厂商的文档接入的,请特别注意:上游文档写的是 JSON + 公网图片 URL 的形式(
multipart/form-data 文件上传发送 JSON 到 /v1/images/edits 会固定返回 400:request Content-Type isn't multipart/form-data
{"image": {"type": "image_url", "url": "..."}}),这套写法在 API易 网关上走不通,请以本页为准。好消息是文件上传不需要图床——直接传本地文件即可,比准备公网 URL 更省事。文件字段名只能是 image 或 image[];写成 images / image_file 会返回 415。prompt 必填,缺失返回 400。场景说明:本页用于「基于一张或多张参考图改图 / 多图融合」。如需纯文本生成图片,请使用 文生图接口。
⚠️ 输出画幅跟随输入图,改不了
resolution 与 aspect_ratio 在本端点传入不报错也不生效——编辑结果的尺寸恒等于输入参考图的尺寸(输入 1280×720 就输出 1280×720,输入 1024×1024 就输出 1024×1024)。需要改变输出画幅,请先自行裁剪或缩放参考图再上传。多图融合顺序有意义:
image[] 可重复传入 1–3 张参考图,上传顺序就是提示词中「图1 / 图2 / 图3」的引用依据。建议在提示词里显式指代,例如「把图1的主体放进图2的场景,沿用图2的画风」。代码示例
Python(OpenAI SDK · 单图编辑)
from openai import OpenAI
import urllib.request
client = OpenAI(
api_key="sk-your-api-key",
base_url="https://api.apiyi.com/v1",
timeout=360.0
)
# SDK 的 images.edit 内部就是 multipart 文件上传,直接传文件对象即可
resp = client.images.edit(
model="grok-imagine-image",
image=open("fox.jpg", "rb"),
prompt="Change the scarf color to bright RED. Keep everything else exactly the same.",
n=1
)
urllib.request.urlretrieve(resp.data[0].url, "edited.jpg")
Python(原生 requests · 单图编辑)
import requests
import urllib.request
API_KEY = "sk-your-api-key"
# 关键:用 files= 传文件(requests 会自动设置 multipart/form-data 及 boundary)
# 千万不要用 json=,那会发成 application/json 并被网关 400 拒绝
with open("fox.jpg", "rb") as fp:
response = requests.post(
"https://api.apiyi.com/v1/images/edits",
headers={"Authorization": f"Bearer {API_KEY}"}, # 不要手动设 Content-Type
data={
"model": "grok-imagine-image",
"prompt": "把围巾改成红色,其余部分完全保持不变",
"n": 1,
"response_format": "url"
},
files={"image": ("fox.jpg", fp, "image/jpeg")},
timeout=360
).json()
urllib.request.urlretrieve(response["data"][0]["url"], "edited.jpg")
Python(多图融合 · 1–3 张)
import requests
API_KEY = "sk-your-api-key"
# 多张参考图用 image[] 重复字段传入,顺序即「图1 / 图2」
files = [
("image[]", ("character.jpg", open("character.jpg", "rb"), "image/jpeg")),
("image[]", ("scene.jpg", open("scene.jpg", "rb"), "image/jpeg")),
]
response = requests.post(
"https://api.apiyi.com/v1/images/edits",
headers={"Authorization": f"Bearer {API_KEY}"},
data={
"model": "grok-imagine-image",
"prompt": "把图1的角色放进图2的场景里,沿用图2的画风和配色",
"response_format": "url"
},
files=files,
timeout=360
).json()
print(response["data"][0]["url"])
cURL
# 单图编辑:-F 即 multipart/form-data,@ 前缀表示上传本地文件
curl -X POST "https://api.apiyi.com/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=grok-imagine-image" \
-F "prompt=把围巾改成红色,其余部分完全保持不变" \
-F "n=1" \
-F "response_format=url" \
-F "[email protected]"
# 多图融合:image[] 重复传入,顺序即「图1 / 图2」
curl -X POST "https://api.apiyi.com/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=grok-imagine-image-quality" \
-F "prompt=把图1的角色放进图2的场景里,沿用图2的画风" \
-F "image[][email protected]" \
-F "image[][email protected]"
Node.js(原生 fetch + FormData)
import fs from 'node:fs';
const form = new FormData();
form.append('model', 'grok-imagine-image');
form.append('prompt', '把围巾改成红色,其余部分完全保持不变');
form.append('n', '1');
form.append('response_format', 'url');
// 单图用 image;多图融合改用 image[] 重复 append(最多 3 张)
form.append('image', new Blob([fs.readFileSync('./fox.jpg')]), 'fox.jpg');
const resp = await fetch('https://api.apiyi.com/v1/images/edits', {
method: 'POST',
// 不要手动设 Content-Type,交给 FormData 自动带 boundary
headers: { 'Authorization': 'Bearer sk-your-api-key' },
body: form,
signal: AbortSignal.timeout(360000)
});
const data = await resp.json();
const img = await fetch(data.data[0].url);
fs.writeFileSync('edited.jpg', Buffer.from(await img.arrayBuffer()));
浏览器 JavaScript
// ⚠️ 仅作演示:Key 写在前端会泄露,生产环境请走后端代理
const fileInput = document.querySelector('#file'); // <input type="file">
const form = new FormData();
form.append('model', 'grok-imagine-image');
form.append('prompt', '把背景换成雪夜的松林,保持人物不变');
form.append('response_format', 'url');
form.append('image', fileInput.files[0]);
const resp = await fetch('https://api.apiyi.com/v1/images/edits', {
method: 'POST',
headers: { 'Authorization': 'Bearer sk-your-api-key' },
body: form
});
const data = await resp.json();
document.querySelector('#preview').src = data.data[0].url;
参数说明速查
| 参数名 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
model | string | ✅ | — | grok-imagine-image($0.02/张)或 grok-imagine-image-quality($0.045/张) |
prompt | string | ✅ | — | 编辑指令。建议写明「改什么」并声明「其余保持不变」 |
image | file | ✅ | — | 参考图文件。多图融合用 image[] 重复传入,1–3 张 |
n | integer | ❌ | 1 | 出图数量 1–10,按张计费,与参考图数量无关 |
response_format | string | ❌ | url | url 返回图片直链;b64_json 返回纯 base64(不带 data: 前缀) |
resolution | string | ❌ | — | 本端点不生效,输出画幅跟随输入图 |
aspect_ratio | string | ❌ | — | 本端点不生效,输出画幅跟随输入图 |
本系列不支持 mask 局部重绘。要局部修改请在提示词里描述清楚修改范围,例如「只把围巾改成红色,其余部分完全保持不变」——模型对这类约束遵循度很好。
编辑效果与提示词写法
编辑接口会保留输入图的画风、构图、配色与主体身份,只改提示词指定的部分。为了拿到稳定结果,建议:| 写法 | 效果 |
|---|---|
✅ 把围巾改成红色,其余部分完全保持不变 | 只有围巾变色,画风/构图/背景逐像素保留 |
✅ 给这只猫加一副圆形黑色墨镜,其余保持不变 | 只加墨镜,原有描边风格与背景色不变 |
✅ 把图1的角色放进图2的场景,沿用图2的画风 | 双图融合,两张图的特征都保留 |
⚠️ 让它更好看一点 | 指令过于笼统,改动范围不可控 |
**显式声明「其余保持不变」**是这个模型上最有效的技巧。多图融合时则要显式指代「图1 / 图2」,对应
image[] 的上传顺序。响应格式
{
"created": 0,
"data": [
{
"url": "https://apac.ossforai.com/2026/08/12/09b026d5-3492-4678-907c-e25972e6c914.jpg"
}
],
"usage": {
"prompt_tokens": 1000,
"total_tokens": 1000
}
}
响应字段陷阱
data[]每项只有url或b64_json二选一,取决于response_format,不会同时出现。- 不返回
revised_prompt,解析时不要假设它存在。 b64_json是纯 base64,不带data:image/...;base64,前缀,可直接base64.b64decode。created恒为0,不能当时间戳用。- 输出尺寸由输入图决定,不要按请求参数去预判返回图的宽高。
usage 不能用来核账:prompt_tokens 恒为 1000 × n,是占位值。编辑与文生图同价,按次固定计费,真实扣费请以 API易 控制台账单为准。授权
在 API易控制台获取的 API Key
请求体
multipart/form-data
模型 ID
可用选项:
grok-imagine-image, grok-imagine-image-quality 编辑指令。建议明确「改什么」并声明「其余保持不变」,例如
Change the scarf color to bright RED. Keep everything else exactly the same.
示例:
"Change the scarf color to bright RED. Keep everything else exactly the same."
参考图文件。多图融合时用 image[] 重复传入(1–3 张),
顺序即 prompt 中「图1/图2/图3」的引用依据。格式 png / jpg / webp。
生成图片数量,取值 1–10。与参考图数量无关
必填范围:
1 <= x <= 10示例:
1
返回格式。url 返回图片直链;b64_json 返回纯 base64(不带 data: 前缀)
可用选项:
url, b64_json 示例:
"url"
此页面对您有帮助吗?
⌘I