GPT Image 2: espelho global e proxy para equipes internacionais
Modelo alvo:
gpt-image-2
Endpoint de inferência:https://api.toapis.com/v1/images/generations
Relacionado: Guia da API GPT Image 2 · Preços do GPT Image 2 · Guia da API GPT-Image-2.6
1. TL;DR e visão geral de desempenho
- Tarefa: apontar clientes internacionais para um único gateway de imagens da ToAPIs, em vez de abrir uma sessão de longa distância nova contra uma origem do fornecedor para cada requisição ao
gpt-image-2. - Contrato: use o ID de modelo
gpt-image-2emPOST /v1/images/generations. Os campos documentados atuais incluemprompt(até 32,000 caracteres),sizecomo proporção como1:1ou16:9(não uma string de pixels1024x1024) eresolutioncomo1k,2kou4k. - Regiões: a documentação oficial da ToAPIs orienta usuários da China continental a usar
https://toapis.cncomo URL base. Os exemplos internacionais desta série de blog usamhttps://api.toapis.com. Caminhos, IDs de modelo e o cabeçalho Bearer continuam iguais; só a origem muda. - Protocolo assíncrono: a geração de imagens retorna um
idde tarefa. ConsulteGET /v1/images/generations/{task_id}(ouGET /v1/tasks/{task_id}) até o status sercompletedoufailed. O tempo de relógio no cliente não é a mesma coisa que o tempo de geração, e um timeout do cliente não prova que a tarefa falhou. - O que este artigo não afirma: ele não publica uma lista de POP, um tempo de handshake nem um alvo de latência de ponta a ponta sem verificação. Meça isso no seu próprio caminho. O detalhe de parâmetros e as comparações de SKU estão no guia da API e no guia do 2.6.
2. Roteando equipes internacionais pelo gateway da ToAPIs
Equipes fora da região de origem do fornecedor normalmente sentem dois atrasos distintos: o tempo para estabelecer uma conexão e o tempo que o modelo realmente passa renderizando. Juntar os dois em um único número de "a API está lenta" faz com que se otimize a coisa errada. O primeiro é um problema de rede que você pode resolver usando uma origem documentada da ToAPIs mais próxima e reutilizando uma sessão HTTP aquecida. O segundo é o tempo de geração, que você observa depois que a tarefa é aceita.
A ToAPIs expõe um caminho unificado de geração de imagens. A documentação oficial atualmente documenta https://toapis.com e orienta usuários na China continental a substituir essa origem por https://toapis.cn. Os guias desta série, incluindo o guia da API GPT Image 2, enviam os mesmos caminhos para https://api.toapis.com. Escolha uma URL base por ambiente, guarde-a como configuração e não codifique uma mistura de origens no mesmo serviço.

Figura 1: mantenha os clientes em uma única origem documentada da ToAPIs, reutilize a sessão e trate a geração de imagens como uma tarefa assíncrona em vez de uma viagem síncrona de longa distância.
Hábitos práticos de roteamento que não dependem de números de latência não publicados:
- Uma origem por ambiente. Um serviço em Cingapura e outro em Frankfurt podem compartilhar o mesmo ID de modelo e payload. Eles não deveriam inventar suas próprias URLs de fornecedor.
- Reutilize conexões. Ative HTTP keep-alive (e HTTP/2 onde seu cliente já suporta) para que o estabelecimento de TLS não se repita em cada envio ou consulta.
- Desacople o envio da espera. Guarde o
idda tarefa imediatamente. Consulte em intervalos limitados, ou melhor, use um webhook de tarefas e mantenha a consulta como reserva. - Não trate "prompts idênticos" como atalho de cobrança. Não há garantia documentada da ToAPIs de que um prompt repetido seja servido por um cache na borda ou seja gratuito. Se duas tarefas são enviadas, planeje pagar por duas tarefas, a menos que os termos da sua conta digam o contrário.
O contrato de requisição atual também fica desatualizado com facilidade. Alguns trechos antigos enviam size como 1024x1024 e um flag quality: "standard". A referência atual da API do gpt-image-2 e o contrato do frontend da ToAPIs usam size para a proporçã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 ou auto) e resolution para o nível (1k, 2k, 4k). O gpt-image-2 exato não expõe um campo quality no contrato atual do playground; quality aparece em IDs como gpt-image-2-vip. Confirme o ID que você realmente chama.
As imagens de referência ficam em reference_images (somente URLs públicas, até 14). image_urls é aceito como alias retrocompatível e é normalizado para reference_images. Não envie base64; suba primeiro. Para proporções personalizadas, mais opções de qualidade ou comportamento de SKU oficial, veja o guia da API e o guia do modelo.
3. Implementação em produção: cURL e Python
Passo 1: envio com cURL
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": "Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography",
"size": "1:1",
"resolution": "1k",
"n": 1,
"response_format": "url"
}'
Passo 2: helper em Python para enviar e consultar
Ajuste os nomes de campo e o envelope de resposta à referência da API da sua conta. O trecho usa o caminho de status de imagem documentado e os status completed / failed. Mude BASE para https://toapis.cn apenas em um ambiente da China continental que deva usar essa origem.
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 = "1:1",
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 = 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__":
task_id = dispatch_image(
"Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography"
)
print("Task:", task_id)
print("Image:", poll_image_task(task_id))
Guarde a URL base, o ID de modelo, size e resolution junto ao registro da tarefa. Se mais tarde você mudar um cliente de gpt-image-2 para gpt-image-2-vip ou para uma SKU do 2.6, mude uma variável por vez e releia o guia correspondente: 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. Uma consulta HTTP bem-sucedida 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 o ID de modelo, se size é uma proporção documentada, se resolution é 1k / 2k / 4k e se as imagens de referência são URLs em vez de base64 |
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 nem de artigos antigos. As tarifas do catálogo, os multiplicadores por resolução e o tratamento de tarefas com falha variam conforme a SKU e a conta. Alguns IDs do GPT Image 2.x são cobrados por imagem; o guia do 2.6 documenta a cobrança por tokens para aquela geração. Confirme a tarifa aplicável ao ID de modelo exato que você chama.
- O roteamento não muda, por si só, o preço do modelo. Usar
api.toapis.comoutoapis.cné uma escolha de URL base. Não é um desconto documentado. Os ganhos de FinOps vêm de evitar envios duplicados após um timeout do cliente, rascunhar em1ke escolher a SKU correta. - Contratos oficiais do fornecedor costumam acrescentar restrições regionais de cobrança, compromissos ou pisos de pré-pagamento. A cobrança da ToAPIs normalmente é por uso: confirme os termos ativos na sua conta.
- Para uma discussão de tarifas mais profunda, use o artigo de preços do GPT Image 2 como contexto 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: mudar a origem da ToAPIs não altera o ID de modelo nem a forma documentada da requisição; usuários da China continental devem seguir a nota sobre toapis.cn na documentação oficial; as tarefas de imagem são assíncronas; size é uma proporção e resolution é o nível; não há cache gratuito na borda documentado para prompts repetidos.
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 comgpt-image-2,size: "1:1"eresolution: "1k". - Guarde o
idda tarefa, consulteGET /v1/images/generations/{id}com um prazo limitado e respeiteRetry-Afterem429. - Em seguida: o guia da API GPT Image 2 para parâmetros, o guia do 2.6 se você for mudar de SKU, e o passo a passo de créditos grátis se você estiver abrindo uma conta nova.







