Dominar inpainting e outpainting com a API de edição de imagens do GPT Image 2
Modelos alvo:
gpt-image-2,gpt-image-2-official
Endpoint de inferência:https://api.toapis.com/v1/images/generations
Relacionado: Guia da API GPT Image 2 · Fluxos de proporção em 4K · Espelho e proxy global · Referência oficial de inpainting
1. TL;DR e visão geral de desempenho
- Tarefa: substituir uma região de uma imagem existente (inpainting) ou estender o canvas para uma nova proporção (outpainting) sem inventar uma segunda API não documentada.
- Contrato: use os IDs de modelo que existem no catálogo. O
gpt-image-2exato aceitaprompt,sizecomo proporção,resolutioncomo1k/2k/4kereference_imagesopcional. O inpainting com máscara está documentado nogpt-image-2-officialcomimage_urlsmaismask_url. - O que não é o contrato atual: um ID de modelo chamado
gpt-image-2-edit, umPOST /v1/images/editsmultipart síncrono, ousize: "1024x1024". Essas formas aparecem em rascunhos antigos e não devem ser copiadas para clientes novos. - E/S: suba as imagens de origem e as máscaras com
POST /v1/uploads/imagese depois passe a URL pública retornada. Base64 não é aceito emreference_images,image_urlsnemmask_url. - Protocolo assíncrono: a chamada de envio retorna um
idde tarefa. ConsulteGET /v1/images/generations/{id}até o status sercompletedoufailed. Um timeout do cliente não prova que a tarefa falhou.
2. O poder da edição programática de imagens
Gerar uma imagem estática a partir de um prompt de texto é apenas o primeiro passo. Catálogos, anúncios e sistemas de design em produção normalmente precisam de uma revisão direcionada: trocar um produto, limpar um fundo ou esticar uma foto de produto quadrada até um hero largo, mantendo a iluminação e a identidade do sujeito.
A família atual GPT Image 2 da ToAPIs cobre esses trabalhos em um caminho, POST /v1/images/generations, com dois IDs de modelo diferentes:
| Tarefa | ID de modelo | Como você aponta para a origem | Máscara? |
|---|---|---|---|
| Edição guiada por prompt ou transferência de estilo | gpt-image-2 | reference_images (lista de URLs, máximo 14) | Não documentada neste ID |
| Inpainting com precisão de pixel | gpt-image-2-official | image_urls (lista de URLs, máximo 16) | mask_url obrigatório com a primeira imagem |
| Expansão de canvas (outpainting) | Qualquer um dos IDs | Passe o original como referência e mude size para a proporção alvo | Sem flag de outpaint dedicado |
image_urls é um alias retrocompatível de reference_images no gpt-image-2 exato e é normalizado pelo gateway. Os exemplos de canal oficial na referência da API usam image_urls junto com mask_url. Use os nomes de campo da referência correspondentes ao ID que você realmente chama.
Uma máscara de inpainting utilizável é um PNG com canal alfa. As dimensões em pixels devem coincidir com a primeira imagem de referência. Pixels transparentes (alpha = 0) são a zona a regenerar; pixels opacos devem ser preservados. Construa a máscara no seu pipeline (por exemplo com Pillow), suba e envie apenas a URL.
O outpainting é um fluxo de trabalho, não um endpoint separado. Se você tem uma foto de produto em 1:1 e precisa de um banner 16:9, mantenha o original como referência, defina size como 16:9, escolha um nível de resolution explícito e instrua o modelo a manter o sujeito e estender a cena. Uma variante prática é compor o original sobre um canvas transparente maior, subir esse canvas e tratá-lo como referência: continua sendo /v1/images/generations, e continua sem um flag outpaint: true.

Figura 1: um canvas de origem e uma região interna mascarada passam pelo gateway da ToAPIs; o caminho documentado continua sendo POST /v1/images/generations, com mask_url reservado ao gpt-image-2-official.
size e resolution seguem o mesmo contrato de texto para imagem: size é uma proporção como 1:1 ou 16:9, e resolution é 1k, 2k ou 4k. O gpt-image-2 exato não expõe um campo quality no contrato atual do playground; quality (low / medium / high) aparece no gpt-image-2-official. Veja o guia de fluxos em 4K para a tabela de pixels documentada.
3. Implementação em produção: cURL e Python
Os exemplos internacionais desta série usam https://api.toapis.com. A documentação oficial orienta usuários da China continental a usar https://toapis.cn. Mantenha uma origem por ambiente. Caminhos, IDs de modelo e o cabeçalho Bearer continuam iguais.
Passo 1: suba uma imagem de origem (e uma máscara, se precisar)
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@./product.png"
A resposta inclui data.url. Repita a chamada para uma máscara PNG quando você chamar o gpt-image-2-official. Não inclua base64 dentro da requisição de geração.
Passo 2: edição guiada por prompt no gpt-image-2 exato
curl -X POST "https://api.toapis.com/v1/images/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "Keep the ceramic kettle and slate surface. Replace only the background with a calm marble countertop, matching the existing side light. No typography.",
"size": "1:1",
"resolution": "1k",
"n": 1,
"response_format": "url",
"reference_images": ["https://example.com/product.png"]
}'
Passo 3: inpainting com máscara no gpt-image-2-official
curl -X POST "https://api.toapis.com/v1/images/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-official",
"prompt": "Replace the masked region with a desert sunset, preserving the subject outline and lighting",
"size": "1:1",
"resolution": "1k",
"quality": "medium",
"image_urls": ["https://example.com/photo.png"],
"mask_url": "https://example.com/mask.png"
}'
Passo 4: helper em Python para enviar e consultar
Ajuste os nomes de campo à referência da API do ID de modelo que você chama. O trecho usa o caminho de status de imagem documentado e os status completed / failed.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def upload_image(path: str) -> str:
with open(path, "rb") as handle:
res = requests.post(
f"{BASE}/v1/uploads/images",
headers=HEADERS,
files={"file": handle},
timeout=60,
)
res.raise_for_status()
url = res.json().get("data", {}).get("url")
if not url:
raise RuntimeError(f"Unexpected upload envelope: {res.text}")
return url
def dispatch_edit(payload: dict) -> str:
res = requests.post(
f"{BASE}/v1/images/generations",
headers={**HEADERS, "Content-Type": "application/json"},
json=payload,
timeout=30,
)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_image_task(task_id: str, deadline_s: int = 180) -> str:
poll_url = f"{BASE}/v1/images/generations/{task_id}"
interval = 2.0
start = time.time()
while time.time() - start < deadline_s:
time.sleep(interval)
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 20))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
interval = min(interval * 1.5, 8.0)
raise TimeoutError(
f"Task {task_id} exceeded {deadline_s}s; check status before retrying"
)
if __name__ == "__main__":
source = upload_image("product.png")
# Prompt-guided edit on exact gpt-image-2 (no mask field on this ID).
task_id = dispatch_edit(
{
"model": "gpt-image-2",
"prompt": "Keep the ceramic kettle; extend the scene into a wide 16:9 set with the same side light. No typography.",
"size": "16:9",
"resolution": "1k",
"n": 1,
"response_format": "url",
"reference_images": [source],
}
)
print("Task:", task_id)
print("Image:", poll_image_task(task_id))
Para executar inpainting com máscara, suba uma máscara RGBA correspondente, mude model para gpt-image-2-official e envie image_urls mais mask_url. Guarde o ID de modelo, size e resolution junto ao registro da tarefa, para que uma mudança posterior de SKU seja uma decisão explícita.
4. Tratamento de erros e matriz de status
As categorias abaixo são pontos de partida para diagnóstico, não uma garantia de códigos de erro exatos da ToAPIs. Um envio HTTP bem-sucedido ainda exige que você leia o status da tarefa.
| Status HTTP | Categoria comum | Ação recomendada |
|---|---|---|
400 | Campo inválido ou combinação não suportada | Confirme o ID de modelo, que size é uma proporção documentada, que resolution é 1k / 2k / 4k, que as URLs são públicas e que uma máscara (quando usada) é um PNG do mesmo tamanho com canal alfa no gpt-image-2-official |
401 | Chave de API ausente ou inválida | Rotacione a chave no painel da ToAPIs e confirme o cabeçalho Authorization |
429 | Limite de taxa ou de concorrência | Respeite Retry-After quando presente; aplique backoff com jitter; tente novamente só quando for seguro |
5xx ou timeout de rede | Problema temporário no gateway ou no upstream | Verifique o status da tarefa antes de reenviar; use uma política de retry limitada |
5. Preços e ROI com FinOps
- Não reutilize preços unitários de rascunhos de planejamento como um par fixo
$0.024/$0.048de "padrão vs HD". Esses números estão desatualizados em relação ao catálogo atual, que cobra por ID de modelo e, na comparação padrão da landing do GPT Image 2, por nível de resolução. - O guia do modelo GPT Image 2 mostra atualmente uma comparação na landing da ToAPIs de
$0.015/$0.020/$0.025por imagem em1K/2K/4Kpara ogpt-image-2padrão. Trate isso como uma comparação publicada, não como uma fatura contratual. SKUs de canal oficial e descontos de conta podem diferir; confirme a tarifa aplicável ao ID exato que você chama. - O roteamento (
api.toapis.comversustoapis.cn) é uma escolha de URL base, não um desconto documentado. Os ganhos de FinOps vêm de rascunhar em1k, evitar envios duplicados após um timeout do cliente e escolher a SKU correta (gpt-image-2versusgpt-image-2-official), em vez de supor um modelo de "edição" mais barato. - Como contexto, veja o artigo de preços do GPT Image 2 e depois confira cada número no catálogo em tempo real antes de colocá-lo em uma previsão.
6. Perguntas frequentes
Veja o bloco FAQ do frontmatter. Resumo: o gpt-image-2 exato não documenta mask_url nem /v1/images/edits; o inpainting com máscara está documentado no gpt-image-2-official; as máscaras devem ser PNG RGBA do mesmo tamanho entregues como URL; o outpainting é uma mudança de size mais uma imagem de referência; a cobrança deve ser confirmada na conta para o ID de modelo exato.
7. Checklist de ações
- Crie uma chave no Portal de desenvolvedores da ToAPIs.
- Defina uma URL base por ambiente (
https://api.toapis.comou, quando necessário,https://toapis.cn) e suba uma imagem de origem comPOST /v1/uploads/images. - Teste uma edição guiada por prompt no
gpt-image-2comreference_images,size: "1:1"eresolution: "1k". - Se precisar de uma máscara com precisão de pixel, mude para
gpt-image-2-official, suba uma máscara RGBA que coincida com a primeira imagem e envieimage_urlsmaismask_url. - Guarde o
idda tarefa, consulteGET /v1/images/generations/{id}com um prazo limitado e respeiteRetry-Afterem429. - Em seguida: o guia de proporção em 4K se você for elevar
resolution, e o guia da API para o mapa completo de parâmetros.







