Documentação da GPT Image API

Visão geral

A GPT Image API oferece geração e edição de imagens com uma única conta e uma única chave de API. As solicitações usam campos familiares no estilo OpenAI (model, prompt, size, quality), o que reduz o custo de migração, enquanto os provedores de modelos ficam abstraídos atrás de uma superfície de API estável. O GPT Image 2 é projetado para imagens com muito texto — ortografia, posicionamento e texto pequeno ou denso devem ser revisados antes da publicação.

Início rápido

1. Crie uma chave de API

Entre no painel e crie uma chave em Configurações → Chaves de API. Armazene o valor no ambiente do seu servidor e nunca o exponha em código do lado do navegador.

GPT_IMAGE_API_KEY=sk_...

2. Escolha um modelo

3. Faça sua primeira solicitação

curl https://api.gptimageapi.dev/v1/images/generations \
  -H "Authorization: Bearer $GPT_IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic product photo of a ceramic coffee cup",
    "size": "1:1"
  }'

Respostas bem-sucedidas retornam as URLs dos ativos gerados em data[].url.

Autenticação

A GPT Image API usa chaves de API com autenticação padrão Bearer.

Authorization: Bearer $GPT_IMAGE_API_KEY

Segurança da chave:

• Nunca coloque uma chave de API em JavaScript do lado do cliente: chame a GPT Image API a partir do seu backend.
• Rotacione as chaves em Configurações → Chaves de API quando um colega sair ou um segredo for exposto.
• Use chaves separadas para desenvolvimento, teste e produção.

Credenciais inválidas ou ausentes retornam 401 Unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key."
  }
}

Endpoints

As solicitações de imagem suportam os endpoints síncronos compatíveis com OpenAI. Tarefas de imagem de longa duração podem ser enviadas de forma assíncrona e consultadas com GET /v1/tasks/{id} até atingirem completed ou failed.

Geração de imagens

POST /v1/images/generations

Edição de imagens

POST /v1/images/edits

Obter resultado de tarefa

GET /v1/tasks/{id}

Status da tarefa: submitted, processing, completed ou failed. Cada tarefa reporta progress de 0 a 100 e um credits_cost ao ser concluída.

Formato de resposta

As respostas de imagem seguem a forma da OpenAI:

{
  "created": 1766880000,
  "data": [
    {
      "url": "https://cdn.gptimageapi.dev/generated/image.png"
    }
  ]
}

As tarefas retornam um id imediatamente:

{
  "status": "submitted",
  "id": "task_01KPQ7J7DWB7QZ3WCEK3YVPBRA",
  "progress": 0,
  "created_at": 1703884800,
  "model": "gpt-image-2"
}

Níveis de qualidade e créditos

Quando o modelo oferece esses parâmetros, o custo em créditos depende do tamanho de saída e do nível de qualidade:

quality=auto é cobrado como high e size=auto usa o nível 1K por padrão. A disponibilidade e as regras de créditos podem mudar; consulte a página de preços antes de solicitações de produção e confira a atividade em Créditos.

Erros

Repita apenas erros transitórios (429, 500, 503) com backoff exponencial. Em 402 insufficient_credits, direcione os usuários para Créditos ou Faturamento para resolverem sem sair do seu fluxo de produto.

Exemplos de código

Node.js

const response = await fetch('https://api.gptimageapi.dev/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GPT_IMAGE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cinematic product photo of a ceramic coffee cup',
    size: '1:1',
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const result = await response.json();
console.log(result.data?.[0]?.url ?? result);

Python

import os
import requests

response = requests.post(
    "https://api.gptimageapi.dev/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_IMAGE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2",
        "prompt": "A cinematic product photo of a ceramic coffee cup",
        "size": "1:1",
    },
)

response.raise_for_status()
result = response.json()
print(result["data"][0]["url"])

Geração assíncrona de imagens (Node.js)

Envie a tarefa e consulte GET /v1/tasks/{id} até que ela seja concluída:

// 1. Envie a tarefa assíncrona
const submit = await fetch('https://api.gptimageapi.dev/v1/async/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GPT_IMAGE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cinematic product photo of a ceramic coffee cup',
    size: '1:1',
  }),
});
const task = await submit.json();
console.log(task.id); // task_01KPQ7J7DWB7QZ3WCEK3YVPBRA

// 2. Consulte até a conclusão
let status = task.status;
while (status === 'submitted' || status === 'processing') {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  const poll = await fetch(`https://api.gptimageapi.dev/v1/tasks/${task.id}`, {
    headers: { Authorization: `Bearer ${process.env.GPT_IMAGE_API_KEY}` },
  });
  const result = await poll.json();
  status = result.status;
  if (status === 'completed') {
    console.log(result.result?.data?.[0]?.url ?? result);
  } else if (status === 'failed') {
    throw new Error(result.error?.message ?? 'Task failed');
  }
}

Geração assíncrona de imagens (Python)

import os
import time
import requests

headers = {"Authorization": f"Bearer {os.environ['GPT_IMAGE_API_KEY']}"}

# 1. Envie a tarefa assíncrona
submit = requests.post(
    "https://api.gptimageapi.dev/v1/async/images/generations",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "model": "gpt-image-2",
        "prompt": "A cinematic product photo of a ceramic coffee cup",
        "size": "1:1",
    },
)
submit.raise_for_status()
task = submit.json()
print(task["id"])

# 2. Consulte até a conclusão
while task["status"] in ("submitted", "processing"):
    time.sleep(2)
    task = requests.get(f"https://api.gptimageapi.dev/v1/tasks/{task['id']}", headers=headers).json()

if task["status"] == "completed":
    print(task["result"]["data"][0]["url"])
else:
    raise RuntimeError(task.get("error", {}).get("message", "Task failed"))

Próximos passos

• Experimente o Playground para testar prompts antes de escrever código.
• Consulte Preços para pacotes de créditos e custos atuais.
• Gerencie chaves, créditos e registros de uso no painel.