Migrar uma API de imagens para a SeedRouter: requisições

Migrar uma API de imagens para a SeedRouter exige conferir o contrato de requisição e resposta, não apenas trocar a chave de API e a URL base. O GPT Image 2 usa os campos habituais de geração de imagens, mas o envio devolve um ID de tarefa. Sua aplicação precisa salvar esse ID, consultar até a conclusão e ler as URLs das imagens prontas.

A menor migração útil é uma requisição de texto para imagem a partir do código do servidor. Faça isso funcionar antes de mover edições com referência, máscaras ou um lote maior. Mantenha a integração atual disponível até que o novo caminho passe pelas mesmas verificações de aceitação.

Quais premissas precisam mudar?

Encontre o código que transforma uma requisição de imagem em um arquivo utilizável. Hoje ele pode esperar uma imagem na resposta inicial, decodificar um campo base64 ou usar upload multipart. Cada uma dessas premissas precisa ser verificada contra a documentação do GPT Image 2 na SeedRouter.

Premissa atual	Contrato da SeedRouter	Mudança na aplicação
O envio devolve a imagem pronta	O envio devolve uma referência de tarefa	Salve `id` antes de esperar a saída
A saída está no array `data` do envio	As imagens da tarefa concluída ficam em `output.data`	Leia os resultados após a conclusão
O cliente decodifica `b64_json`	As imagens voltam como URLs hospedadas	Baixe as URLs retornadas
A edição envia os bytes do arquivo	As referências usam objetos de URL em `images`	Torne as imagens de entrada acessíveis por URL
Um caminho de edição separado seleciona a edição	`images` e `mask` selecionam a operação	Use o endpoint público de geração
Tempo esgotado no cliente significa falha	A tarefa ainda pode estar em processamento	Volte a consultar o ID salvo

Por isso uma chamada síncrona de SDK de imagens não é substituta direta, mesmo que aceite uma URL base configurável. Mantenha os ajustes de modelo de que você ainda precisa, mas adapte o código da aplicação que espera e consome o resultado.

Mapeie os campos da requisição antes de mexer no código

Comece por model, prompt, size, quality e n. Use gpt-image-2 como ID do modelo. Envie dimensões explícitas como 1024x1024 ou use auto; não leve adiante um campo resolution separado nem uma string de proporção como tamanho.

O documento OpenAPI da SeedRouter ajuda nessa revisão. Compare os campos que sua aplicação realmente envia, incluindo valores fornecidos por um SDK, em vez de conferir só os argumentos visíveis no ponto da chamada. Campos desconhecidos são rejeitados.

Para este modelo, style, response_format e um input_fidelity configurável não são campos aceitos na requisição. Elimine essas premissas em vez de escondê-las dentro de um objeto genérico de opções. A requisição também não suporta stream nem partial_images; o status da tarefa é como esta integração informa o andamento.

Os ajustes de saída têm dependências. Se pedir transparência, escolha PNG. Envie output_compression só para JPEG, nunca para PNG. Um valor de compressão igual a zero é válido, então evite uma checagem de veracidade que o substitua por um padrão. São detalhes pequenos que uma requisição básica bem-sucedida não exercita.

Troque a premissa de resposta síncrona

O exemplo em Node.js a seguir envia uma requisição e imprime o ID da tarefa. Defina SEEDROUTER_API_KEY no servidor; nunca coloque a chave em código de navegador nem em variável de ambiente pública.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cobalt-blue ceramic mug on a pale gray tabletop.',
    size: '1024x1024',
    quality: 'low',
    n: 1,
  }),
  signal: AbortSignal.timeout(60000),
});
const task = await response.json();
if (!response.ok) {
  // Preserve a task reference if one accompanies an uncertain submission.
  if (typeof task.id === 'string') console.log('Task reference:', task.id);
  throw new Error(`Submission needs review: HTTP ${response.status}`);
}
if (typeof task.id !== 'string' || !task.id) throw new Error('Missing task ID.');
console.log(task.id); // Persist this ID with your application's image record.

Imprimir o ID basta para um teste manual rápido. Em uma aplicação, guarde-o antes de devolver o controle ao usuário. Assim o registro da imagem pode continuar pendente enquanto a pessoa navega por outras telas, e uma consulta posterior recupera o resultado.

Use GET https://api.seedrouter.ai/v1/tasks/{id} com o mesmo cabeçalho de autorização para acompanhar o andamento. Em completed, leia output.data[].url. Em failed, trate o erro documentado e mostre um estado de falha adequado. Para um exemplo executável que persiste o progresso, veja envio em lote e polling.

Não anexe a chave de API à requisição de download da imagem. A autorização pertence à chamada da API de tarefas, não a uma busca separada da URL de um arquivo retornado.

Passe referências e máscaras para entradas por URL

Um fluxo baseado em arquivos locais precisa de um passo extra de preparação: deixe a imagem de referência disponível em uma URL HTTP(S) acessível que você controla. Passe-a como images: [{"image_url": "https://example.com/reference.png"}], trocando esse endereço pelo seu. Não envie caminho de arquivo, URL blob:, data URL em base64 nem Files ID.

Verifique se a URL funciona sem os cookies de login do seu navegador. Uma URL que só abre na sua sessão autenticada não serve como referência para esta requisição. Mantenha a imagem acessível enquanto a tarefa está em processamento; não revogue o acesso logo depois do envio.

Uma máscara usa mask: {"image_url": "https://example.com/mask.png"} e exige imagens de referência. Ela precisa ter as mesmas dimensões da primeira imagem de referência. Revise todos os limites de entrada de mídia antes de mover um fluxo de edição existente, em especial formatos e tamanhos de arquivo.

O que o teste de aceitação da migração deve cobrir?

Teste o comportamento do qual sua aplicação depende, incluindo interrupções. Uma imagem bem-sucedida prova apenas que aquela requisição funcionou. Não prova que o estado pendente sobrevive a um recarregamento nem que uma falha de download evita geração duplicada.

Envie uma requisição só com texto e guarde o ID retornado antes de fazer polling.
Pare o polling, reinicie com o mesmo ID e confirme que nenhum POST adicional acontece.
Trate processing, completed e failed como estados distintos.
Baixe uma imagem concluída sem enviar o cabeçalho de autorização da API.
Teste uma edição com referência usando uma URL acessível e depois verifique o tratamento de erro com uma inacessível.
Valide os campos opcionais, incluindo compressão igual a zero, usando o schema publicado.
Confirme que as cobranças são lidas no histórico de uso, e não em um campo de custo inventado na resposta da tarefa.

Use respostas simuladas para testes repetíveis de falha e de tempo esgotado. Faça um teste real pequeno e deliberado só depois que essas verificações passarem; gerações reais consomem saldo. Se o resultado do envio for incerto, investigue antes de tentar de novo. Uma exceção local não é prova de que nenhuma tarefa foi aceita.

Perguntas frequentes

Posso manter os prompts que já tenho?

Sim, como ponto de partida, desde que respeitem as restrições da requisição. Guarde alguns prompts representativos para comparação, mas não espere imagens idênticas em gerações repetidas.

Preciso de uma nova biblioteca cliente?

Não para os exemplos daqui. Requisições HTTP comuns bastam. Qualquer cliente que você escolher precisa lidar com envio de tarefa e polling, em vez de esperar uma imagem pronta na hora.

Onde encontro o custo final?

No histórico de uso da conta. Uma tarefa concluída pode incluir o uso de tokens, mas sua resposta pública não tem campo de custo. O guia de preços trata das estimativas.

Termine a migração na fronteira da aplicação

Uma migração de API de imagens está completa quando a aplicação cuida de todo o ciclo de vida do resultado: tarefa aceita, estado pendente, saída pronta, download e falha. Mantenha pequena a primeira mudança, teste os casos de interrupção e mova as demais requisições só depois de verificar suas premissas de entrada e saída.

Mover uma integração de imagens para a SeedRouter