Gerar imagens nativas em 4K com o GPT Image 2: proporções e fluxos de upscaling
Modelo alvo:
gpt-image-2
Endpoint de inferência:https://api.toapis.com/v1/images/generations
Relacionado: Guia da API GPT Image 2 · Inpainting e outpainting · Espelho e proxy global · Referência de tamanhos da API
1. TL;DR e visão geral de desempenho
- Tarefa: produzir uma imagem pronta para impressão ou para um hero no nível 4K documentado, com a proporção que você realmente precisa, a partir de uma única requisição ao
gpt-image-2. - Contrato:
POST /v1/images/generationscom o ID de modelogpt-image-2.sizeé uma proporção (1:1,16:9e as demais proporções documentadas).resolutioné1k,2kou4k. A referência oficial publica as dimensões em pixels resultantes de cada par. - O que não enviar:
size: "2048x2048", um flagquality: "hd"nogpt-image-2exato, ou um campo inventadoupscale: trueque prometa transformar uma renderização de 2048 px em3840x2160. O 4K é um valor deresolutionde primeira classe. - Protocolo assíncrono: a chamada de envio retorna um
idde tarefa. ConsulteGET /v1/images/generations/{id}(ouGET /v1/tasks/{id}) até o status sercompletedoufailed. Tarefas em 4K podem demorar mais do que rascunhos em 1K; um timeout do cliente não prova que a tarefa falhou. - FinOps: faça rascunhos em
1k, promova os prompts aceitos para4ke confirme a tarifa vigente por nível. Não copie linhas de preço antigas de 1024 px / 2048 px para uma previsão.
2. Proporções, níveis de resolução e saída nativa em 4K
O contrato atual do gpt-image-2 separa a forma do nível. size escolhe a proporção; resolution escolhe o nível de qualidade; o serviço deriva a largura e a altura em pixels dos dois. É por isso que uma "imagem em 4K" nem sempre é 3840x2160: esse tamanho é o resultado documentado de size: "16:9" mais resolution: "4k". Uma saída quadrada em 4K está documentada como 2880x2880.
As proporções predefinidas listadas na referência oficial são:
1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21
Você pode enviar auto e deixar o fornecedor upstream escolher, mas então a proporção final e o tamanho em pixels não são garantidos. O gpt-image-2 exato não documenta um campo custom de tamanho em pixels; proporções personalizadas width:height (por exemplo 7:4) estão documentadas em gpt-image-2-vip e gpt-image-2-official, sujeitas aos próprios limites (lados múltiplos de 16, borda longa de no máximo 3,840 px, proporção de no máximo 3:1, total de pixels entre 655,360 e 8,294,400).
A tabela de tamanhos da referência da API para o gpt-image-2 exato é:
| size | 1k | 2k | 4k |
|---|---|---|---|
1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
3:2 | 1536x1024 | 2048x1360 | 3520x2336 |
2:3 | 1024x1536 | 1360x2048 | 2336x3520 |
4:3 | 1024x768 | 2048x1536 | 3312x2480 |
3:4 | 768x1024 | 1536x2048 | 2480x3312 |
5:4 | 1280x1024 | 2560x2048 | 3216x2576 |
4:5 | 1024x1280 | 2048x2560 | 2576x3216 |
16:9 | 1536x864 | 2048x1152 | 3840x2160 |
9:16 | 864x1536 | 1152x2048 | 2160x3840 |
2:1 | 2048x1024 | 2688x1344 | 3840x1920 |
1:2 | 1024x2048 | 1344x2688 | 1920x3840 |
21:9 | 2016x864 | 2688x1152 | 3840x1648 |
9:21 | 864x2016 | 1152x2688 | 1648x3840 |
Duas ressalvas acompanham essa tabela:
- O playground atual da ToAPIs mantém
3:2e2:3em 4K, mas omite5:4e4:5quando a resolução é 4K. A tabela de tamanhos acima ainda lista pixels em 4k para essas duas proporções. Se o seu produto precisa de5:4ou4:5em 4k, confirme com uma requisição real em vez de assumir que o filtro do playground é o limite da API. - Em superfícies diferentes aparecem minúsculas (
4k) e maiúsculas (4K). Os exemplos oficiais dogpt-image-2usam minúsculas; a configuração do playground usa1K/2K/4K. Siga a referência da API nos clientes e não trate maiúsculas como um segundo parâmetro.

Figura 1: a resolução é um campo de requisição de primeira classe. O caminho documentado é pedir 4k diretamente, não inventar um flag de upscaling pós-processamento.
Não existe um interruptor upscale: true documentado na ToAPIs que pegue uma renderização nativa de 2048 px e devolva 3840x2160. Se você já tem uma imagem em 1K ou 2K e quer uma maior, o movimento suportado é uma nova geração (opcionalmente com o rascunho em reference_images) com resolution: "4k". Não prometa fidelidade tipográfica, "originais de impressão a 300 DPI" nem upscaling sem artefatos, a menos que você tenha medido essas propriedades nos seus próprios ativos.
O gpt-image-2 exato também aceita, de forma opcional, background: "transparent" e até 14 URLs em reference_images. Ele não expõe quality no contrato atual do playground; quality é um campo de IDs como gpt-image-2-vip.
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 única origem por ambiente.
Passo 1: envio com cURL em 4K nativo
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": "Wide architectural photograph of a concrete pavilion at dusk, still water in the foreground, no typography, no logos",
"size": "16:9",
"resolution": "4k",
"n": 1,
"response_format": "url"
}'
Esta requisição está documentada para mirar 3840x2160. Para um original quadrado em 4K, mude size para 1:1 (documentado como 2880x2880). Para um frame de story em 9:16, use size: "9:16" (documentado como 2160x3840).
Passo 2: helper em Python para rascunho e promoção
Itere em 1k, guarde o prompt aceito (e as URLs de referência opcionais) e reenvie em 4k. O helper de consulta é o mesmo contrato assíncrono usado no guia de espelho e proxy.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/images/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_image(
prompt: str,
size: str = "16:9",
resolution: str = "1k",
model: str = "gpt-image-2",
reference_images: list[str] | None = None,
) -> str:
payload = {
"model": model,
"prompt": prompt,
"size": size,
"resolution": resolution,
"n": 1,
"response_format": "url",
}
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(ENDPOINT, headers=HEADERS, 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 = 300) -> 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__":
prompt = (
"Wide architectural photograph of a concrete pavilion at dusk, "
"still water in the foreground, no typography, no logos"
)
draft_id = dispatch_image(prompt, size="16:9", resolution="1k")
print("Draft:", draft_id, poll_image_task(draft_id))
final_id = dispatch_image(prompt, size="16:9", resolution="4k")
print("4K:", final_id, poll_image_task(final_id, deadline_s=300))
Dê às consultas em 4K um prazo maior do que aos rascunhos em 1K. Guarde o id da tarefa imediatamente, para que um timeout do cliente possa ser resolvido depois por uma consulta de status. Se mais tarde você mudar o cliente para gpt-image-2-vip (proporções personalizadas, quality) ou gpt-image-2-official, mude uma variável por vez e releia a referência daquele ID: as unidades de cobrança não são automaticamente as mesmas.
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 | Verifique se size é uma proporção documentada, se resolution é 1k / 2k / 4k e se você não enviou uma string de pixels como 2048x2048 nem um flag upscale não documentado |
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; tarefas em 4K podem continuar em in_progress após um timeout do cliente |
5. Preços e ROI com FinOps
- Não reutilize preços unitários antigos como
$0.024para 1024 px ou$0.072para 2048 px. Essas linhas pertencem a um contrato de tamanho obsoleto. - 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. Use isso apenas como comparação publicada. Confirme a tarifa aplicável à sua conta e ao ID de modelo exato que você chama. - Um loop econômico consiste em rascunhar em
1ke depois promover o prompt aceito (e as referências) para4k. Duas tarefas bem-sucedidas são duas imagens cobráveis, a menos que os termos da sua conta digam o contrário. Não existe um atalho gratuito documentado de "upscale do mesmo prompt". - Os preços por token do fornecedor oficial e os preços por requisição da ToAPIs não são intercambiáveis. Se você migrar para
gpt-image-2-vipou para uma SKU de canal oficial, releia a tabela de preços daquele ID. - 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 4K é um valor de resolution de primeira classe, não um flag upscale; as dimensões em pixels dependem de size e de resolution; não envie 1024x1024 como size; confirme 5:4 / 4:5 em 4k contra a API em tempo real se precisar dessas proporções; confirme as tarifas publicadas de 1K / 2K / 4K na sua conta.
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 teste o trecho cURL comsize: "16:9"eresolution: "1k". - Promova o mesmo prompt para
resolution: "4k"e confirme o tamanho em pixels documentado para essa proporção (para16:9,3840x2160). - Guarde o
idda tarefa, dê às consultas em 4K um prazo maior e respeiteRetry-Afterem429. - Em seguida: o guia de inpainting e outpainting se estiver editando um frame existente, e o guia da API para o mapa completo de parâmetros.







