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;type=image/png'import requests
url = "https://api.apiyi.com/v1/images/edits"
files = { "image": ("example-file", open("example-file", "rb"), "image/png") }
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: image/png\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: image/png\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: image/png\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: image/png\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
}
}画像編集 API リファレンス
Grok Imagine 2 の画像編集 API リファレンスとライブテスト — 編集または融合のために参照画像を1〜4枚アップロードし、指示を指定します。multipart/form-data が必要です
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;type=image/png'import requests
url = "https://api.apiyi.com/v1/images/edits"
files = { "image": ("example-file", open("example-file", "rb"), "image/png") }
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: image/png\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: image/png\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: image/png\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: image/png\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
}
}Default グループには含まれていません。独自の**Grok_imagine_Reverse グループ**に属しており、呼び出し(このページの Playground を含む)を行う前にアクセスの申請が必要です。申請がない場合、すべての呼び出しは 503 を返します。このファミリーのコンテンツ安全ポリシーはプラットフォーム上の他のモデルと大きく異なり、一部のカテゴリはフィルタリングされないため、コンプライアンスリスクを抑える目的でアクセス権を選択的に付与しています。累積利用額が $1,000 以上のお客様は、サポートにユースケースを説明することで有効化できます。それ以外の方は、WeCom サポートを通じて、ユースケースおよび導入済みのコンテンツモデレーション管理体制を明記の上お申し込みください。完全な手順はGrok Imagine 2 概要 - グループ設定をご確認ください。Bearer sk-xxx)、image ファイルを選択し、prompt と model を入力して送信してください。multipart/form-data ファイルアップロードが必要です/v1/images/edits に JSON を送信すると、常に 400 が返されます:request Content-Type isn't multipart/form-data
{"image": {"type": "image_url", "url": "..."}})を含む JSON 本文が記載されていますが、その形式は APIYI ゲートウェイ経由では動作しません。代わりにこのページの手順に従ってください。メリットとして、ファイルアップロードを行うことで画像のホスティングが不要になります。公開 URL を準備するよりも簡単なローカルファイルを直接送信するだけで済みます。ファイルフィールド名は image または image[] である必要があります。images / image_file は 415 を返します。prompt は必須です。省略すると 400 が返されます。resolution と aspect_ratio はエラーなく受け入れられますが、効果はありません。編集後の出力は常に最初の参照画像のサイズと一致します(入力が 1280x720 の場合は出力も 1280x720、入力が 1024x1024 の場合は出力も 1024x1024 になります)。これは合成の場合にも当てはまります。4枚の参照画像の順序を逆にすると、出力サイズは 1280x720 から 1024x1024 に切り替わり、新しい1枚目の画像に従います。出力サイズを変更したい場合は、アップロード前に最初の参照画像をトリミングまたはリサイズしてください。image[] は 1〜4枚 の参照画像を受け入れます(実測の上限は4枚で、5枚目を指定すると 400 を返します)。そして、アップロードした順序が、prompt 内で言及される「image 1 / image 2 / image 3」に対応します。「put the subject from image 1 into the scene from image 2, keeping image 2’s art style」のように明示的に指定してください。2枚/3枚/4枚の参照画像で実測した結果、画像が1枚追加されるごとに出力に対応する被写体が追加され、それぞれの特徴が維持されました。合成は実用的に機能します。コード例
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
)
# The SDK's images.edit already performs a multipart upload — pass the file object directly
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 (生のリクエスト、単一画像)
import requests
import urllib.request
API_KEY = "sk-your-api-key"
# Key point: use files= so requests sets multipart/form-data and the boundary for you.
# Never use json= — that sends application/json and the gateway rejects it with 400.
with open("fox.jpg", "rb") as fp:
response = requests.post(
"https://api.apiyi.com/v1/images/edits",
headers={"Authorization": f"Bearer {API_KEY}"}, # do NOT set Content-Type manually
data={
"model": "grok-imagine-image",
"prompt": "Change the scarf to red, keep everything else exactly the same",
"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-4ファイル)
import requests
API_KEY = "sk-your-api-key"
# Repeat the image[] field for multiple references — order is "image 1 / image 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": "Put the character from image 1 into the scene from image 2, "
"keeping image 2's art style and palette",
"response_format": "url"
},
files=files,
timeout=360
).json()
print(response["data"][0]["url"])
cURL
# Single-image edit: -F means multipart/form-data, @ uploads a local file
curl -X POST "https://api.apiyi.com/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=grok-imagine-image" \
-F "prompt=Change the scarf to red, keep everything else exactly the same" \
-F "n=1" \
-F "response_format=url" \
-F "[email protected]"
# Multi-image fusion: repeat image[], order is "image 1 / image 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=Put the character from image 1 into the scene from image 2, keep image 2's style" \
-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', 'Change the scarf to red, keep everything else exactly the same');
form.append('n', '1');
form.append('response_format', 'url');
// Single image uses `image`; for fusion append `image[]` repeatedly (max 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',
// Do not set Content-Type manually — let FormData supply the 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
// ⚠️ Demo only: a front-end key is exposed — use a backend proxy in production
const fileInput = document.querySelector('#file'); // an <input type="file"> element
const form = new FormData();
form.append('model', 'grok-imagine-image');
form.append('prompt', 'Replace the background with a snowy pine forest at night, keep the subject');
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/image) または grok-imagine-image-quality ($0.045/image) |
prompt | string | ✅ | — | 編集指示。何を変更するかと、それ以外はすべてそのままにすることを記してください |
image | file | ✅ | — | 参照画像ファイル。融合の場合は image[] を繰り返し、1-4 files(5つ目は400を返します)。最初の1つが出力寸法を設定します |
n | integer | ❌ | 1 | 出力画像数、1-10、参照数に関係なく画像ごとに課金されます |
response_format | string | ❌ | url | url は直接リンクを返します。b64_json は生のbase64を返します(data: プレフィックスはありません) |
resolution | string | ❌ | — | ここでは効果はありません — 出力は入力画像に従います |
aspect_ratio | string | ❌ | — | ここでは効果はありません — 出力は入力画像に従います |
編集動作とプロンプトスタイル
編集エンドポイントは、入力画像のアートスタイル、構図、パレット、被写体のアイデンティティを保持し、prompt が指定した内容だけを変更します。安定した結果を得るには:| プロンプトスタイル | 結果 |
|---|---|
✅ Change the scarf to red, keep everything else exactly the same | スカーフだけが変更され、スタイル、構図、背景は保持されます |
✅ Add round black sunglasses to the cat, keep everything else unchanged | サングラスが追加されるだけで、輪郭スタイルと背景色はそのままです |
✅ Put the character from image 1 into the scene from image 2, keep image 2's style | 両方の入力の特徴を保持する融合です |
⚠️ Make it look better | 曖昧すぎます — 変更範囲が予測不能になります |
image[] のアップロード順に合わせて、必ず「image 1 / image 2」を参照してください。また、最も重要な被写体を最初に置いてください: 最初の画像は出力サイズを決めるだけでなく、テストでは順序を逆にすると副次的な被写体のアイデンティティが別の被写体に混ざってしまいました。レスポンス形式
{
"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[]エントリには、response_formatに応じてurlまたはb64_jsonのどちらか一方のみが含まれます — 両方は含まれません。 revised_promptは返されません — 存在すると仮定しないでください。b64_jsonはdata:image/...;base64,接頭辞のない生の base64 です — そのままデコードしてください。createdは常に0であり、タイムスタンプとして使用できません。- 出力サイズは 入力画像 によって決定されるため、リクエストパラメータから幅/高さを予測しないでください。
usageは照合に使用できません: prompt_tokens は常に 1000 x n であり、プレースホルダーです。編集料金は text-to-image と同じで、画像ごとの定額料金です。実際の請求額は APIYI コンソールの課金記録を参照してください。承認
API Key created in the APIYI Console
ボディ
Model ID
grok-imagine-image, grok-imagine-image-quality Editing instruction. State what to change and explicitly ask for everything else to stay put,
e.g. 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."
Reference image file. For multi-image fusion repeat the image[] field (1-4 files);
upload order is what "image 1 / image 2 / image 3" refers to in the prompt, and
the first file also determines output dimensions. Each added image contributes
a subject in testing. Accepted formats: png / jpg / webp.
Number of output images, 1-10. Independent of the number of reference images
1 <= x <= 101
Response format. url returns a direct link; b64_json returns raw base64 (no data: prefix)
url, b64_json "url"
レスポンス
Image generated successfully
Creation timestamp. Always 0 for this model — do not use it for timing
0
Array of image results, length equals the requested n
Show child attributes
Show child attributes
Placeholder values — do not use for billing reconciliation. prompt_tokens is always 1000 x n
Show child attributes
Show child attributes
このページは役に立ちましたか?