图片编辑:根据指令编辑参考图或融合多图
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