Imagem para imagem (edição de imagens)

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Use this reference image to create a more polished square product hero image while preserving the main style.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image=@reference.png'

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)",
      "revised_prompt": "<string>"
    }
  ]
}

POST

images

edits

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Use this reference image to create a more polished square product hero image while preserving the main style.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image=@reference.png'

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)",
      "revised_prompt": "<string>"
    }
  ]
}

POST /v1/images/edits O endpoint de imagem para imagem usa um corpo de solicitação multipart/form-data. Envie uma ou mais imagens de referência e informe prompt e parâmetros como campos de formulário.

Use https://bettertoken.ai/v1 como Base URL. Envie sua BetterToken API Key por Authorization: Bearer YOUR_API_KEY.

Você pode preencher os campos e enviar imagens de referência no Playground à direita da página e enviar a solicitação diretamente para https://bettertoken.ai/v1/images/edits.

Não use um corpo JSON comum em solicitações de imagem para imagem. Envie campos de texto e de arquivo com multipart/form-data.

Valores recomendados

Envie estes campos explicitamente em todas as solicitações:

model=gpt-image-2
n=1
response_format=b64_json
output_format=png

Use image para uma única referência. Para várias referências, repita os campos image[].

Uma imagem de referência

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer sk-***REDACTED***' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Use this reference image to create a more polished square product hero image while keeping the main style consistent.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image=@reference.png'

Várias imagens de referência

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer sk-***REDACTED***' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Combine these reference images into one consistent promotional poster.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image[]=@reference-1.png' \
  -F 'image[]=@reference-2.jpg' \
  -F 'image[]=@reference-3.png'

Edite uma área selecionada com máscara

Adicione o campo de arquivo opcional mask quando quiser direcionar a edição para uma área selecionada. O endpoint atual da BetterToken lê um único arquivo em mask. Não envie campos mask[] repetidos.

A imagem original e a máscara devem ter o mesmo formato e as mesmas dimensões em pixels. Cada arquivo deve ter menos de 50 MB. Para máxima compatibilidade, use PNG com canal Alpha nos dois arquivos.
A máscara deve conter um canal Alpha. Pixels totalmente transparentes (Alpha 0) marcam a área que o modelo pode redesenhar. Pixels totalmente opacos (Alpha 255) orientam o modelo a preservar essa área.
Uma imagem RGB comum em preto e branco não é uma máscara válida se não tiver de fato um canal Alpha.
Se você enviar vários campos image[], a máscara será aplicada à primeira imagem de entrada.
A máscara orienta o modelo. Ela não garante que os pixels fora da área transparente permaneçam absolutamente idênticos.

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer sk-***REDACTED***' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Replace only the masked area with a blue circle. Preserve everything else.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image=@original.png' \
  -F 'mask=@mask.png'

Edição com máscara em Python

Abra os dois arquivos em uma única instrução with para que o Python os feche após a solicitação:

import requests

url = "https://bettertoken.ai/v1/images/edits"
headers = {"Authorization": "Bearer sk-***REDACTED***"}
data = {
    "model": "gpt-image-2",
    "prompt": "Replace only the masked area with a blue circle. Preserve everything else.",
    "n": "1",
    "size": "1024x1024",
    "response_format": "b64_json",
    "output_format": "png",
}

with open("original.png", "rb") as image_file, open("mask.png", "rb") as mask_file:
    files = {
        "image": ("original.png", image_file, "image/png"),
        "mask": ("mask.png", mask_file, "image/png"),
    }
    response = requests.post(url, headers=headers, data=data, files=files, timeout=300)

response.raise_for_status()
result = response.json()

Verifique os arquivos antes do upload

Esta verificação mínima com Pillow valida os requisitos de formato, dimensões e canal Alpha. Para uma máscara local típica, ela também exibe um aviso se o canal Alpha não incluir áreas totalmente transparentes e opacas:

from pathlib import Path
from PIL import Image

image_path = Path("original.png")
mask_path = Path("mask.png")

if image_path.stat().st_size >= 50 * 1024 * 1024 or mask_path.stat().st_size >= 50 * 1024 * 1024:
    raise ValueError("Each file must be smaller than 50 MB")

with Image.open(image_path) as image, Image.open(mask_path) as mask:
    if image.format != mask.format:
        raise ValueError("The image and mask formats must match")
    if image.size != mask.size:
        raise ValueError("The image and mask dimensions must match")
    if "A" not in mask.getbands():
        raise ValueError("The mask must contain an Alpha channel")
    alpha_min, alpha_max = mask.getchannel("A").getextrema()
    if alpha_min > 0 or alpha_max < 255:
        print("Warning: for a typical local mask, include fully transparent and fully opaque areas")

Exemplo em Python

import requests

url = "https://bettertoken.ai/v1/images/edits"
headers = {
    "Authorization": "Bearer sk-***REDACTED***",
}

data = {
    "model": "gpt-image-2",
    "prompt": "Use this reference image to create a more polished square product hero image while keeping the main style consistent.",
    "n": "1",
    "size": "1024x1024",
    "response_format": "b64_json",
    "output_format": "png",
}

with open("reference.png", "rb") as image_file:
    files = {
        "image": ("reference.png", image_file, "image/png"),
    }
    response = requests.post(url, headers=headers, data=data, files=files, timeout=300)

response.raise_for_status()
result = response.json()
b64_json = result["data"][0]["b64_json"]

Tamanhos recomendados

`size`	Proporção	Caso de uso
`auto`	Automática	Seleção automática de tamanho
`1024x1024`	`1:1`	Imagens quadradas, avatares, capas e materiais
`1536x1024`	`3:2`	Pôsteres, banners e cenas horizontais
`1024x1536`	`2:3`	Capas e pôsteres verticais para celular
`1536x1152`	`4:3`	Imagens horizontais padrão, imagens de produto e gráficos de conteúdo
`1152x1536`	`3:4`	Imagens verticais padrão, capas de celular e pôsteres verticais
`2048x2048`	`1:1`	Imagens quadradas de alta resolução
`2048x1152`	`16:9`	Imagens horizontais de alta resolução
`3840x2160`	`16:9`	Imagens horizontais em 4K
`2160x3840`	`9:16`	Imagens verticais em 4K

size representa a proporção esperada e a faixa de tamanho. Os pixels retornados podem ser mapeados ou ajustados pelo servidor. Use as dimensões da imagem decodificada em vez de cortar à força a saída para o valor solicitado.

Salve a imagem

Uma resposta bem-sucedida segue o formato de resposta de imagem compatível com OpenAI:

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)"
    }
  ]
}

Leia data[0].b64_json e salve-o como conteúdo de imagem base64. Sempre defina output_format: "png" para salvar a imagem decodificada como .png.

Fluxo de resposta

Este endpoint é síncrono. Depois de enviar POST /images/edits, mantenha a solicitação HTTP aberta até o servidor responder. Quando a geração for concluída, o conteúdo da imagem será retornado em data[0].b64_json. O endpoint não retorna task_id, nem há endpoint separado para consultar status ou baixar o resultado.

Documentos relacionados

Autorizações

Authorization

string

header

obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Corpo

multipart/form-data

model

enum<string>

padrão:gpt-image-2

obrigatório

Use the GPT Image 2 model ID.

Opções disponíveis:

gpt-image-2

Exemplo:

"gpt-image-2"

prompt

string

obrigatório

Instructions for editing the image or generating from reference images.

Exemplo:

"Use this reference image to create a more polished square product hero image while preserving the main style."

image

file

The reference image field for a single input image.

image[]

file[]

Repeat this field for each input when sending multiple reference images.

mask

file

An optional single mask file. The mask and original image must have the same format and dimensions, each file must be smaller than 50 MB, and the mask must contain an Alpha channel. For maximum compatibility, use PNG with an Alpha channel for both files. With multiple image[] inputs, the mask applies to the first image.

padrão:1

Use 1. Send separate requests when you need multiple output images.

Exemplo:

"1"

size

enum<string>

padrão:1024x1024

The requested image size or aspect-ratio tier. The server may map or adjust the final pixel dimensions, so inspect the decoded image for its actual size.

Opções disponíveis:

auto,

1024x1024,

1536x1024,

1024x1536,

1536x1152,

1152x1536,

2048x2048,

2048x1152,

3840x2160,

2160x3840

Exemplo:

"1024x1024"

response_format

enum<string>

padrão:b64_json

Use b64_json.

Opções disponíveis:

b64_json

Exemplo:

"b64_json"

output_format

enum<string>

padrão:png

Use png. Do not rely on jpeg or webp being returned directly in the selected format.

Opções disponíveis:

png

Exemplo:

"png"

Resposta

Image editing result.

created

integer

Exemplo:

1710000000

data

object[]

Show child attributes

​Valores recomendados

​Uma imagem de referência

​Várias imagens de referência

​Edite uma área selecionada com máscara

​Edição com máscara em Python

​Verifique os arquivos antes do upload

​Exemplo em Python

​Tamanhos recomendados

​Salve a imagem

​Fluxo de resposta

​Documentos relacionados

Autorizações

Corpo

Resposta

Valores recomendados

Uma imagem de referência

Várias imagens de referência

Edite uma área selecionada com máscara

Edição com máscara em Python

Verifique os arquivos antes do upload

Exemplo em Python

Tamanhos recomendados

Salve a imagem

Fluxo de resposta

Documentos relacionados