GPT Image 2.5 API: gerar e editar imagens em Python

Envie um POST para https://api.omniakey.com/v1/media/tasks com o model definido como gpt-image-2.5-flare, consulte o id da tarefa que volta e baixe assets[0].url quando o status estiver succeeded. Em 29 de outubro de 2026 geramos em 1K, 2K e 1536x1024 e editamos uma foto de café; abrimos cada arquivo e lemos o tamanho real em pixels: 1024×1024, 2048×2048, 1536×1024 e 1024×682. A geração em 1K levou 29,5 s e a em 2K, 45,2 s.

Qual id do modelo 2.5 usar

Use gpt-image-2.5-flare. Foi o id que chamamos em todas as execuções abaixo. A página do modelo GPT-Image 2.5 Flare (verificada em 29 de outubro de 2026) aponta a OpenAI como provedora, lista texto para imagem e edição de imagem e traz a nota "Guide updated 2026-10-27". A mesma página mostra um segundo id 2.5, gpt-image-2.5-sunburst.

O Flare dá conta dos dois trabalhos. Gerar envia um prompt; editar envia um prompt mais uma imagem de origem. A qualidade aceita low, medium ou high, e a mesma página diz que o nível não muda o preço. Todas as execuções aqui usaram medium. Não rodamos sunburst, qualidade low ou high, 4K nem 3840x2160, máscaras ou várias imagens de referência, então planeje com o Flare em medium e uma única imagem de origem até testar o resto por conta própria.

O código da requisição

O script abaixo é o que rodamos, sem alterações: dois helpers, depois uma chamada de geração e uma de edição. Ele usa apenas a biblioteca padrão do Python, lê sua chave de OMNIAKEY_API_KEY e grava cada PNG na pasta de onde você o executa.

import base64
import json
import os
import time
import urllib.request
import uuid

API = "https://api.omniakey.com/v1/media/tasks"
KEY = os.environ["OMNIAKEY_API_KEY"]
MODEL = "gpt-image-2.5-flare"

def request(method, url, body=None, extra_headers=None):
    headers = {"Authorization": f"Bearer {KEY}", "User-Agent": "omniakey-example/1"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    headers.update(extra_headers or {})
    req = urllib.request.Request(url, data=data, headers=headers, method=method)
    with urllib.request.urlopen(req, timeout=120) as resp:
        return json.load(resp)

def run_task(body, out_path):
    task = request("POST", API, body, {"Idempotency-Key": str(uuid.uuid4())})["id"]
    for _ in range(150):
        time.sleep(4)
        state = request("GET", f"{API}/{task}")
        if state["status"] not in ("queued", "processing"):
            break
    if state["status"] != "succeeded":
        raise RuntimeError(state.get("error") or state["status"])
    asset_url = state["assets"][0]["url"]  # signed link: valid for about an hour, so download now
    req = urllib.request.Request(asset_url, headers={"User-Agent": "omniakey-example/1"})
    with urllib.request.urlopen(req, timeout=120) as resp, open(out_path, "wb") as f:
        f.write(resp.read())
    return task

def generate_image(prompt, out_path, size="1K", quality="medium"):
    body = {
        "model": MODEL,
        "type": "image",
        "operation": "generate",
        "input": {"prompt": prompt},
        "parameters": {"size": size, "quality": quality},
    }
    return run_task(body, out_path)

def edit_image(source_path, prompt, out_path, size="1K", quality="medium"):
    with open(source_path, "rb") as f:
        image = base64.b64encode(f.read()).decode()
    body = {
        "model": MODEL,
        "type": "image",
        "operation": "edit",
        "input": {"prompt": prompt, "image": {"data": image, "mime_type": "image/jpeg"}},
        "parameters": {"size": size, "quality": quality},
    }
    return run_task(body, out_path)

if __name__ == "__main__":
    task = generate_image(
        "A small glass greenhouse on a hillside at sunrise, morning fog in the valley, "
        "soft watercolor style, a wooden bench outside the door, no people, no text.",
        "greenhouse.png",
    )
    print("generate task", task)
    task = edit_image(
        "cafe-base.jpg",
        "Change the red bicycle to matte black. Keep everything else exactly the same: "
        "the table, the cup, the window frame and the daylight. Photorealistic, no text, no logos.",
        "cafe-edited.png",
    )
    print("edit task", task)

Authorization: Bearer <key> vai em todas as chamadas, e a chamada de criação também precisa de um Idempotency-Key, que o script preenche com um UUID novo. O corpo define type como "image", operation como "generate" ou "edit", as palavras em input.prompt e o tamanho e a qualidade em parameters. A API também aceita n, e só 1 é válido, por isso o script o deixa de fora. Uma criação retorna HTTP 202 com um id de tarefa, o status começa em queued, e o loop espera 4 s entre as verificações até sair dos dois estados de trabalho.

Uma edição adiciona o JPEG em input.image como um objeto Base64 embutido com o tipo mime. Corpos de requisição, Base64 incluído, têm limite de 1 MiB, então o script envia um JPEG de 1024 pixels com cerca de 230 KB.

Os tamanhos que rodamos e o que voltou

Quatro execuções, todas com qualidade medium, em 29 de outubro de 2026. Três voltaram no tamanho que pedimos. A edição em 1K não voltou assim em uma das duas execuções.

• 1K, gerar — Tamanho em pixels lido do arquivo: 1024×1024; Data: 29 de outubro de 2026
• 2K, gerar — Tamanho em pixels lido do arquivo: 2048×2048; Data: 29 de outubro de 2026
• 1536x1024, gerar — Tamanho em pixels lido do arquivo: 1536×1024; Data: 29 de outubro de 2026
• 1K, editar — Tamanho em pixels lido do arquivo: 1024×682; Data: 29 de outubro de 2026

A estufa abaixo é uma geração em 1K feita com o mesmo corpo de requisição do código acima.

Duas coisas para levar da lista. Primeiro, leia o tamanho no arquivo que você baixou. A edição em 1K pediu um quadrado e voltou com 1024×682, o formato do JPEG de 1024×683 que enviamos, e outra execução da mesma edição em 1K voltou com 1024×1024. Segundo, a lista de tamanhos da documentação da API de imagens (verificada em 29 de outubro de 2026) oferece auto, 1K, 2K, 4K e 3840x2160 para este modelo e diz que recusa tamanhos fora da lista antes de qualquer cobrança; a nossa chamada de 1536x1024 em 29 de outubro de 2026 não foi recusada e retornou 1536×1024. Confira o arquivo real antes de montar um layout em cima de um tamanho.

Uma edição mantém a cena e muda uma coisa

Uma edição responde a duas perguntas: o que muda e o que fica. Pedimos uma mudança e nomeamos o que precisava sobreviver.

Prompt: "Change the red bicycle to matte black. Keep everything else exactly the same: the table, the cup, the window frame and the daylight. Photorealistic, no text, no logos."

A bicicleta voltou escura, e a mesa, a xícara, a planta e o batente da janela continuavam no quadro. A origem era um JPEG de 1024×683, a saída mediu 1024×682 e a execução levou 38,0 s. Escreva a lista do que fica em toda edição: para a estrutura de prompts em geral, veja o nosso guia de prompts do GPT Image 2.

Erros e limites

Dois cabeçalhos fazem o trabalho antes de existir qualquer pixel: o token bearer e um Idempotency-Key único. Com eles certos, o resto da chamada fica simples de repetir.

A chave pode ter até 255 caracteres, segundo a documentação verificada em 29 de outubro de 2026. Repetir com o mesmo corpo é a retentativa segura: você recebe a tarefa existente e nada novo é cobrado. Mantenha o corpo abaixo de 1 MiB, Base64 incluído, então redimensione ou comprima a origem antes de enviar.

Quando uma tarefa dá certo, assets[0].url é um link assinado que dura cerca de uma hora, segundo a documentação, então baixe na hora ou consulte a mesma tarefa de novo para pegar um link novo. Os registros de tarefa ficam por 24 horas.

Um cabeçalho nos surpreendeu em 29 de outubro de 2026: um POST enviado com o User-Agent padrão do urllib do Python retornou HTTP 403 com o corpo "error code: 1010" vindo do Cloudflare. O mesmo POST com o nosso próprio cabeçalho User-Agent: omniakey-example/1 chegou à API, que respondeu 400 invalid_request para o corpo vazio que enviamos, e nada foi cobrado. A documentação cita só Authorization e Idempotency-Key, então defina um User-Agent no seu cliente.

GPT Image 2.5 ou GPT Image 2 para trabalhar com API?

O Flare é o id 2.5 que testamos. O GPT Image 2, na página do modelo GPT Image 2, usa o id gpt-image-2. Se um script já entrega o que você precisa nesse id, não há motivo para trocar.

Para uma foto que precisa manter a cena enquanto um objeto muda, o Flare em medium é o que as nossas execuções de 29 de outubro de 2026 cobrem: três tamanhos gerados e a edição de 1024×682. A comparação entre GPT Image 2.5 e GPT Image 2 tem tamanhos e resultados do mesmo prompt para os dois modelos, para você escolher com números na frente. As tarifas atuais estão na página de preços.

Perguntas frequentes

Qual id de modelo devo usar, gpt-image-2.5-flare ou gpt-image-2.5-sunburst?

Rodamos o Flare em todas as execuções acima, e a edição dele manteve a cena que pedimos para manter. A página do modelo lista o Sunburst como o segundo id 2.5: comece pelo Flare e submeta o Sunburst à sua edição mais difícil antes de trocar.

Posso pedir um tamanho horizontal como 1536x1024?

Em 29 de outubro de 2026 uma geração em 1536x1024 voltou com 1536×1024. A lista de tamanhos da documentação da API de imagens não inclui esse valor para este modelo, então leia o arquivo e confira a documentação antes de depender dele em produção.

Por que minha edição voltou num tamanho diferente do que pedi?

A mesma edição em 1K voltou com 1024×682 em uma execução e com 1024×1024 em outra, então trate o tamanho pedido como um pedido, não como promessa. Abra o PNG e leia a largura e a altura antes de posicioná-lo.

Preciso de um cabeçalho User-Agent?

Em 29 de outubro de 2026 uma requisição com o User-Agent padrão do Python recebeu HTTP 403 com o erro 1010 do Cloudflare. A mesma requisição com o nosso próprio cabeçalho User-Agent chegou à API, então envie um.

Quanto tempo duram os links das imagens?

A documentação diz que o link assinado dura cerca de uma hora. Consulte a tarefa de novo para pegar um link novo e baixe o arquivo assim que a tarefa der certo.