Skip to main content
POST
Image editing: edit a reference image or fuse several
오른쪽의 대화형 Playground는 로컬 파일 업로드를 지원합니다. Authorization에 API 키를 입력하고(형식: Bearer sk-xxx), image 파일을 하나 선택한 다음, promptmodel를 입력하고 전송하십시오.
🔴 이 엔드포인트는 multipart/form-data 파일 업로드가 필요합니다/v1/images/edits에 JSON을 보내면 항상 400을 반환합니다:
특히 xAI 또는 상위 공급업체의 문서에서 연동하는 경우 이 점이 중요합니다: 해당 문서는 공개 이미지 URL({"image": {"type": "image_url", "url": "..."}})이 포함된 JSON 본문을 설명하지만, 그 형식은 APIYI 게이트웨이에서는 작동하지 않습니다. 대신 이 페이지를 따르십시오.장점은 파일 업로드를 사용하면 이미지 호스팅이 필요 없다는 점입니다. 즉, 로컬 파일만 보내면 되므로 공개 URL을 준비하는 것보다 더 간단합니다.파일 필드의 이름은 image 또는 **image[]**이어야 합니다. images / image_file415를 반환합니다. prompt는 필수입니다 — 생략하면 400을 반환합니다.
이 페이지를 사용하는 경우: 참조 이미지 하나를 편집하거나 여러 이미지를 융합할 때입니다. prompt만으로 생성할 때는 텍스트-투-이미지 엔드포인트를 사용하십시오.
⚠️ 출력 치수는 입력 이미지에 따르며 변경할 수 없습니다resolutionaspect_ratio는 여기서 오류 없이 허용되지만 아무 효과가 없습니다 — 편집된 출력은 항상 입력 참조 이미지의 치수와 일치합니다(1280x720 입력 시 1280x720 출력, 1024x1024 입력 시 1024x1024 출력).출력 크기를 변경하려면 업로드하기 전에 참조 이미지를 자르거나 크기 조정하십시오.
융합 순서는 중요합니다: image[]1-3개의 참조 이미지를 지원하며, 업로드 순서가 prompt에서 말하는 “image 1 / image 2 / image 3”를 의미합니다. 이를 명시적으로 적으십시오. 예: “image 1의 주제를 image 2의 장면에 넣되, image 2의 예술 스타일은 유지하십시오”.

코드 예제

Python (OpenAI SDK, 단일 이미지)

Python (원시 요청, 단일 이미지)

Python (멀티 이미지 융합, 1-3개 파일)

cURL

Node.js (네이티브 fetch + FormData)

브라우저 JavaScript

매개변수 참조

이 계열은 마스크 인페인팅을 지원하지 않습니다. 변경 범위를 제한하려면 prompt에 정확히 설명하십시오. 예를 들어 “스카프만 빨간색으로 바꾸고, 나머지는 모두 정확히 동일하게 유지하십시오”와 같이 작성합니다. 모델은 이러한 제약을 엄격하게 따릅니다.

편집 동작과 프롬프트 스타일

편집 엔드포인트는 입력 이미지의 아트 스타일, 구도, 색상 팔레트 및 피사체 정체성을 유지하고, prompt가 지정한 내용만 변경합니다. 안정적인 결과를 얻으려면:
“다른 모든 내용은 변경하지 말라”고 명시적으로 말하는 것이 이 모델에서 가장 효과적인 기법입니다. 융합의 경우에는 항상 image[] 업로드 순서에 맞춰 “이미지 1 / 이미지 2”를 참조하십시오.

응답 형식

응답 필드 주의사항
  • data[] 항목에는 response_format에 따라 url 또는 b64_json 중 하나만 포함됩니다 — 둘 다는 아닙니다.
  • revised_prompt은 반환되지 않습니다 — 존재한다고 가정하지 마십시오.
  • b64_jsondata:image/...;base64, 접두사가 없는 원시 base64입니다 — 바로 디코드하십시오.
  • created는 항상 0이며 타임스탬프로 사용할 수 없습니다.
  • 출력 차원은 입력 이미지에 의해 결정되므로 요청 파라미터로 너비/높이를 예측하지 마십시오.
usage은 정산에 사용할 수 없습니다: prompt_tokens는 항상 1000 x n인 플레이스홀더입니다. 편집 비용은 이미지당 정액 요율로 텍스트-투-이미지와 동일하며, 실제 과금은 APIYI 콘솔 과금 기록을 사용하십시오.

인증

Authorization
string
header
필수

API Key created in the APIYI Console

본문

multipart/form-data
model
enum<string>
기본값:grok-imagine-image
필수

Model ID

사용 가능한 옵션:
grok-imagine-image,
grok-imagine-image-quality
prompt
string
필수

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."

image
file
필수

Reference image file. For multi-image fusion repeat the image[] field (1-3 files); upload order is what "image 1 / image 2 / image 3" refers to in the prompt. Accepted formats: png / jpg / webp.

n
integer
기본값:1

Number of output images, 1-10. Independent of the number of reference images

필수 범위: 1 <= x <= 10
예시:

1

response_format
enum<string>
기본값:url

Response format. url returns a direct link; b64_json returns raw base64 (no data: prefix)

사용 가능한 옵션:
url,
b64_json
예시:

"url"

응답

Image generated successfully

created
integer

Creation timestamp. Always 0 for this model — do not use it for timing

예시:

0

data
object[]

Array of image results, length equals the requested n

usage
object

Placeholder values — do not use for billing reconciliation. prompt_tokens is always 1000 x n