Guia de migração da API GPT Image: como mudar de Responses para a Images API e manter a edição de imagens em várias rodadas?

Guia de migração da API GPT Image: como mudar de Responses para a Images API e manter a edição de imagens em várias rodadas?

Nota do autor: quem já usa image_generation do Responses na APIYI para “conversar e gerar imagens ao mesmo tempo” pode, após migrar para a API Images independente, manter a edição contínua de imagens seguindo os métodos deste artigo.

Resumo antecipado: migre somente a parte de geração de imagens; o diálogo de texto existente não precisa ser alterado. Antes, a “imagem anterior” era conectada implicitamente por meio de previous_response_id; agora, seu aplicativo precisa salvá-la e selecioná-la explicitamente a cada edição, enviando-a como imagem original para POST /v1/images/edits. Com isso, o efeito da edição em várias rodadas permanece o mesmo; o que muda é apenas quem se lembra da “imagem anterior”.

Essa conclusão tem como premissa a atualização de documentação publicada pela APIYI em 21/11/2026 às 22:30 (horário de Pequim). Cinco modelos de imagem com proxy oficial passaram a ser recomendados por meio de dois endpoints de imagem independentes. A OpenAI não desativou o Responses, e os diálogos de texto no site continuam funcionando normalmente. Todas as interfaces, campos e critérios de cobrança abaixo vêm da documentação da APIYI em apiyi.com e do guia oficial de geração de imagens da OpenAI. O código é um exemplo de documentação e não representa resultados de testes reais.

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-pt-pt-image-0


Mapa de conhecimento e índice para a migração da GPT Image API

A migração inteira avança em quatro etapas, e a saída de cada etapa é a entrada da próxima:

Identificar chamadas antigas e separar rotas (Seção 1)
   └─> Saída: definir, para cada requisição, se ela vai para chat, generations ou edits
Gerar e salvar a primeira imagem (Seção 2.1)
   └─> Saída: v1.png validado + registro do ativo
Entregar a imagem original escolhida à interface de edição (Seção 2.2)
   └─> Saída: v2.png + vínculo parent_asset_id
Aceitação e conferência de contas (Seção 3)
   └─> Saída: lista de imagens utilizáveis + custo por imagem aceita

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-pt-pt-image-1

Etapa Do que depende Por que fica aqui Objetivo
1 Separação de rotas Lista de chamadas no código atual Primeiro definir o que mudar, para não alterar por engano o chat de texto Mover apenas as requisições de geração de imagem para a Images API
2.1 Primeira geração A rota generations definida na etapa 1 As edições seguintes precisam de uma imagem original realmente salva Obter um v1 validado e registrado
2.2 Continuação das edições O arquivo v1 salvo na etapa 2.1 O endpoint independente não reconhece previous_response_id, só reconhece a imagem que você envia Obter um v2 e registrar a relação pai-filho
3 Aceitação e conferência As imagens e os logs do console da etapa 2 Só imagens aprovadas entram no denominador de custo Imagens entregáveis + fatura explicável

Ordem de leitura sugerida: a Seção 1 é obrigatória; na Seção 2, siga o código na ordem; a Seção 3 serve para consulta antes do lançamento ou quando aparecerem desconexões e dúvidas sobre a cobrança.

To Know: Terminologia da migração da GPT Image API

Termo Explicação resumida
官转 (encaminhamento oficial) Modelo de canal de encaminhamento oficial oferecido pela APIYI; neste artigo, refere-se aos cinco IDs de modelos de imagem
image_generation Ferramenta de geração de imagens dentro da Responses API; a cadeia antiga gera imagens enquanto conversa por meio dela
previous_response_id Parâmetro que a Responses usa para continuar o contexto da rodada anterior; requisições independentes da Images não o aceitam
multipart Formato de upload de formulário; o /images/edits usa esse formato para enviar o binário real da imagem
b64_json Campo pelo qual o endpoint independente de imagens retorna a imagem; o conteúdo é a imagem codificada em base64
parent_asset_id Campo de associação que a própria aplicação registra: “de qual imagem esta foi derivada”

1 Quais chamadas da GPT Image API precisam ser migradas do Responses

1.1 O escopo da atualização de 21/11 da GPT Image API e os cinco modelos oficiais convertidos

Esta atualização da documentação envolve os cinco IDs de modelos oficiais convertidos a seguir:

  • gpt-image-2.6-sunburst
  • gpt-image-2.6-flare
  • gpt-image-2.5-sunburst
  • gpt-image-2.5-flare
  • gpt-image-2

Os dois endpoints de imagem independentes correspondentes são POST /v1/images/generations (corpo de requisição JSON) e POST /v1/images/edits (formulário multipart). A APIYI não recomenda continuar usando o fluxo image_generation do Responses para gerar imagens, por dois motivos: instabilidade de fornecimento e cobrança de taxa adicional por uso de ferramenta. Além disso, o Chat Completions não suporta gerar imagens com esses cinco modelos oficiais convertidos; se o código antigo tiver esse uso, ele também precisa entrar na lista de migração.

Vale esclarecer que esse ajuste afeta apenas a geração de imagens. A OpenAI não desativou o Responses, e o chat de texto dentro da APIYI também continua ativo. Portanto, o escopo da migração se limita à parte do código que “chama a ferramenta de imagem ou o modelo de imagem na requisição”. Como escolher entre os cinco modelos é outro assunto — consulte o artigo de seleção de modelos no central de ajuda da APIYI (apiyi.com); este texto não entra nesse mérito.

1.2 GPT Image API: diálogo em texto, primeira geração e roteamento de edições posteriores

A combinação sugerida na FAQ da APIYI é: o modelo de diálogo avalia a intenção do usuário, e a aplicação chama a Images API separadamente, gerenciando as imagens por conta própria. Seguindo essa lógica, as três tarefas que antes eram resolvidas em uma única requisição ao Responses podem ser divididas em três rotas:

Intenção do usuário Nova rota Formato da requisição Origem da imagem
Conversa puramente textual, perguntas e respostas Manter a interface de diálogo em texto existente Inalterado Nenhuma
Primeira geração de imagem POST /v1/images/generations JSON Somente prompt
Continuar editando uma imagem POST /v1/images/edits multipart A aplicação envia a imagem original já selecionada

No Responses nativo, a edição continuada pode ser feita via previous_response_id ou passando a imagem diretamente. Uma requisição independente à Images API não aceita previous_response_id — essa é a razão fundamental pela qual “edições em múltiplas rodadas” precisam ser gerenciadas pela aplicação. O modelo não guarda mais a última imagem por você; é você quem precisa entregar o arquivo daquela imagem a ele.

Se o usuário disser “deixa mais vermelho”, mas a sessão já tiver várias versões — v1, v2, v3 — a aplicação não consegue determinar a qual versão ele se refere. Nesse caso, confirme com o usuário primeiro, não adivinhe. Usar a versão mais recente por padrão parece prático, mas se o usuário na verdade queria voltar para a v2 e refazer a edição, você acaba cobrando uma vez a mais sem necessidade e ainda confunde o usuário.

A análise da resposta também precisa mudar junto:

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-pt-pt-image-2

Fluxo Onde a imagem fica na resposta Como o contexto é continuado
Responses + image_generation O result do item com type=image_generation_call em output previous_response_id ou envio da imagem
Images API independente data[0].b64_json A aplicação envia a imagem original já selecionada

2 Como continuar editando a imagem anterior com o GPT Image API

Um exemplo de duas rodadas ajuda a mostrar o fluxo completo. A primeira rodada gera uma caneca azul e, na segunda, só o corpo da caneca muda para vermelho-tijolo. Os parâmetros seguem o exemplo da documentação da APIYI: modelo gpt-image-2.5-sunburst, tamanho 1024x1024, quality=medium, output_format=png. O token é lido da variável de ambiente APIYI_KEY e passado como Bearer.

2.1 Gerar e validar o PNG da caneca azul com o GPT Image API

A primeira rodada chama o endpoint generations, e o comando descreve: fundo cinza-claro, caneca de cerâmica azul centralizada, alça voltada para a direita, luz suave vindo de lado e nenhum texto na imagem. Depois de receber a resposta, siga esta ordem:

  1. Chame raise_for_status() para primeiro descartar falhas no nível HTTP.
  2. Faça uma decodificação base64 estrita do b64_json; se não decodificar, já conta como falha.
  3. Abra com Pillow e chame load() para confirmar que o arquivo realmente decodifica em uma imagem.
  4. Confirme que o formato é PNG e o tamanho é 1024×1024, depois salve como v1.png.
  5. Registre esse asset na aplicação; as próximas edições partem daqui para pegar a imagem original.

Não dá para pular a etapa 3. open() lê apenas o cabeçalho do arquivo; se os dados da imagem estiverem truncados, isso só aparece quando você chama load().

2.2 GPT Image API: enviar a imagem original selecionada e alterar apenas o corpo da caneca para vermelho-tijolo

Segunda rodada: chamar o endpoint edits. Em data, envie model, prompt, size, quality e output_format; em files, use o campo image[] para enviar os bytes reais de v1.png. O comando significa: altere apenas o corpo da caneca para vermelho-tijolo; mantenha a forma da caneca, a alça, a composição, a iluminação e o fundo inalterados.

Há alguns pontos propensos a erro nesta etapa:

  • Não envie response_format.
  • Não escreva o Content-Type manualmente. O requests gera automaticamente o cabeçalho multipart com boundary; escrever à mão acaba por perder o boundary.
  • Não envie uma string base64 como se fosse um arquivo; o que deve ser enviado são os bytes originais da imagem.

Depois de editar, decodifique e valide da mesma forma e salve como v2.png. O v1 deve ser mantido e, no registro do ativo, registre parent_asset_id = v1. Essa relação pai-filho é o “contexto de múltiplas rodadas” sob a nova arquitetura. Vale notar também que esta é uma edição generativa: o modelo vai tentar preservar as outras áreas, mas não garante que os pixels fora do corpo da caneca sejam idênticos um a um.

A seguir, um exemplo mínimo completo (exemplo de documentação, não testado neste artigo):

import base64
import io
import os
import uuid

import requests
from PIL import Image

BASE_URL = "https://api.apiyi.com/v1"  # endpoint unificado da APIYI
API_KEY = os.environ["APIYI_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
MODEL = "gpt-image-2.5-sunburst"
SIZE = "1024x1024"
# Timeout intermediário de exemplo; ajuste conforme sua rede e qualidade. Sem retry automático.
TIMEOUT = (10, 360)

assets = {}  # asset_id -> {"path": ..., "parent_asset_id": ...}


def decode_and_check(resp, path):
    resp.raise_for_status()
    item = resp.json()["data"][0]
    b64 = item.get("b64_json")
    if not b64:
        raise ValueError("no b64_json in response, check body before any resend")
    raw = base64.b64decode(b64, validate=True)
    img = Image.open(io.BytesIO(raw))
    img.load()
    if img.format != "PNG" or img.size != (1024, 1024):
        raise ValueError(f"unexpected image: {img.format} {img.size}")
    with open(path, "wb") as f:
        f.write(raw)
    return path


def save_asset(path, parent_asset_id=None):
    asset_id = str(uuid.uuid4())
    assets[asset_id] = {"path": path, "parent_asset_id": parent_asset_id}
    return asset_id


# Rodada 1: texto para imagem via JSON
gen_resp = requests.post(
    f"{BASE_URL}/images/generations",
    headers=HEADERS,
    json={
        "model": MODEL,
        "prompt": (
            "Light gray background, a blue ceramic mug centered, "
            "handle facing right, soft side lighting, no text."
        ),
        "size": SIZE,
        "quality": "medium",
        "output_format": "png",
    },
    timeout=TIMEOUT,
)
v1_id = save_asset(decode_and_check(gen_resp, "v1.png"))

# Rodada 2: editar o original selecionado explicitamente via multipart
selected_id = v1_id  # se a versão desejada pelo usuário não estiver clara, pergunte primeiro
with open(assets[selected_id]["path"], "rb") as f:
    edit_resp = requests.post(
        f"{BASE_URL}/images/edits",
        headers=HEADERS,  # sem Content-Type manual; o requests define o boundary
        data={
            "model": MODEL,
            "prompt": (
                "Change only the mug body to brick red. Keep the mug shape, "
                "handle, composition, lighting and background unchanged."
            ),
            "size": SIZE,
            "quality": "medium",
            "output_format": "png",
        },
        files={"image[]": ("v1.png", f, "image/png")},
        timeout=TIMEOUT,
    )
v2_id = save_asset(decode_and_check(edit_resp, "v2.png"), parent_asset_id=selected_id)
print(assets)

No exemplo, timeout=(10, 360) é apenas uma configuração intermediária da documentação; o valor real deve ser definido conforme o seu link de rede e o nível de qualidade de imagem. O exemplo também omite deliberadamente o retry automático — o motivo está na seção 3.2.

🚀 Validação rápida: defina APIYI_KEY como o token que você criou no painel do APIYI apiyi.com, e o script acima consegue executar as duas rodadas completas do fluxo. Quem está começando pode primeiro usar a cota gratuita de testes para confirmar a lógica de roteamento e de parsing, e depois migrar para o tráfego de produção.

gpt-image-api-migrate-responses-to-images-api-multi-turn-edit-pt-pt-image-3


3 Como validar e conferir a contabilidade após a migração para a GPT Image API

3.1 As quatro etapas de validação de imagens da GPT Image API

Só quando as quatro etapas são todas aprovadas é que uma imagem pode ser marcada como “disponível” na aplicação:

  1. HTTP bem-sucedido: o raise_for_status() não lançou exceção.
  2. Decodificável: a decodificação base64 estrita foi bem-sucedida e o load() do Pillow também.
  3. Especificações corretas: formato e dimensões iguais aos da requisição; neste exemplo, PNG, 1024×1024.
  4. A mudança visual realmente aconteceu: o corpo do copo na v2 realmente ficou vermelho-tijolo, e o formato do copo, a alça, a composição e o fundo permaneceram basicamente iguais.

A 4ª etapa exige inspeção humana ou uma etapa de revisão separada, porque o código de status HTTP não mostra se o modelo alterou corretamente. Uma imagem que passa apenas nas três primeiras etapas, no máximo, é considerada “tecnicamente válida” e ainda não pode ser entregue. Se a resposta não tiver imagem nenhuma, vale a pena verificar primeiro o conteúdo da resposta antes de decidir se tenta novamente; o centro de ajuda tem um artigo dedicado a esse assunto, e não vamos repeti-lo aqui.

3.2 A antiga taxa de ferramenta da GPT Image API e o custo por imagem validada

Antes e depois da migração, a base de cobrança é diferente:

Item Antiga cadeia Responses image_generation Images API independente
Custo extra Cerca de US$ 0,20 de taxa extra de chamada da ferramenta de imagens do APIYI Sem essa taxa de ferramenta
O que esse número significa Refere-se apenas a essa taxa extra de ferramenta, não ao preço total do pedido, nem ao preço geral da OpenAI Cobrança por uso
Forma de comparação adequada Comparar por “custo por imagem validada” Comparar por “custo por imagem validada”

Não compare apenas o preço unitário; o ideal é usar uniformemente a fórmula abaixo:

Custo por imagem validada = cobranças reais relacionadas (incluindo as chamadas de texto necessárias, requisições falhas já cobradas e novas tentativas) ÷ número de imagens aprovadas na validação

O numerador deve incluir todas as cobranças relacionadas, incluindo as chamadas de conversa para identificar a intenção, as requisições falhas já cobradas e as novas tentativas. O denominador conta apenas as imagens que passaram nas quatro etapas da seção 3.1. Se não houver nenhuma imagem aprovada, não calcule o custo unitário, porque a conclusão nesse caso deve ser “o processo tem problema”, e não “o preço unitário é alto”. Quanto a migração pode economizar depende da sua taxa de novas tentativas e da taxa de aprovação na validação; este artigo não fornece proporções específicas.

Os dados para conferir a conta vêm do log de consumo do console, em que o registro de consumo tem type=2. Se estiver lendo o campo quota, converta para valor monetário usando quota ÷ 500000, conforme a documentação da plataforma.

O tratamento de desconexão merece atenção especial. O endpoint independente de imagens retorna de forma síncrona; quando a conexão cai no meio do caminho, essa requisição pode já ter sido cobrada, e não é possível recuperar a imagem pelo request ID. A ordem correta é: primeiro conferir no log de consumo do console do APIYI apiyi.com se essa requisição foi cobrada, e só depois decidir se é preciso reenviar. Esse é também o motivo pelo qual o código de exemplo não implementa novas tentativas automáticas — retentativas automáticas facilmente causam cobrança duplicada quando a conexão cai. Se você enfrentar limitação de taxa ou precisar trocar de canal, consulte o artigo do centro de ajuda sobre seleção de canal e degradação 429.

O critério para considerar a migração concluída é bem direto: o diálogo por texto continua funcionando normalmente; a primeira geração de imagem retorna de forma estável um v1 que passa pelas quatro etapas; toda alteração de imagem tem um parent_asset_id claramente identificável no registro de ativos; e cada cobrança de imagem no log do console corresponde a uma imagem validada, a uma falha conhecida ou a um reenvio registrado. Quando todos esses itens estiverem atendidos, você pode migrar o restante do tráfego de geração de imagem do Responses para a Images API. Quando precisar de testes comparativos entre vários modelos, o APIYI apiyi.com oferece uma interface compatível com OpenAI unificada; para trocar de modelo, basta alterar um parâmetro: MODEL.


Materiais de referência

  1. Atualização da documentação do APIYI: modelos de imagem com relay oficial passam a usar a Images API

    • Link: docs.apiyi.com/live/2026-11/gpt-image-official-relay-images-api
    • Descrição: os cinco IDs de relay oficial, os dois endpoints independentes e os motivos para não recomendar o fluxo antigo
  2. FAQ do APIYI: processar texto e imagem ao mesmo tempo em uma única API

    • Link: docs.apiyi.com/faq/text-and-image-in-one-api
    • Descrição: como o modelo de conversa identifica a intenção e como a aplicação combina chamadas separadas à Images API
  3. Guia de geração de imagens da OpenAI

    • Link: developers.openai.com/api/docs/guides/image-generation
    • Descrição: o modo de edição continuada do Responses e a estrutura da resposta
  4. APIYI GPT Image 2: texto para imagem / edição de imagens

    • Link: docs.apiyi.com/api-capabilities/gpt-image-2/text-to-image
    • Link: docs.apiyi.com/api-capabilities/gpt-image-2/image-edit
    • Descrição: parâmetros da requisição, upload multipart e exemplos de validação de decodificação
  5. APIYI: ferramenta de imagem do Responses / boas práticas da API de imagens / consulta de logs

    • Link: docs.apiyi.com/api-capabilities/gpt-image-2/responses-image-tool
    • Link: docs.apiyi.com/api-capabilities/image-api-best-practices
    • Link: docs.apiyi.com/api-capabilities/log-query
    • Descrição: critério de cobrança da ferramenta, tratamento de desconexão e conversão dos logs de consumo

Autor: Equipe técnica da APIYI
Contato técnico: se você encontrar problemas de roteamento ou de cobrança durante a migração, fale conosco pela página inicial do APIYI apiyi.com. Para mais detalhes sobre as interfaces, consulte o centro de documentação em docs.apiyi.com

Artigos relacionados

Similar Posts