A migração
O que está implementado
Suportado
POST /v1/async/taskPOST /v1/async/task/batchGET /v1/async/task/{id}Callbacks de webhookNão implementado
Endpoints síncronos
/v1/monitor/*/v1/async/status/v1/monitor/* está ausente de propósito. Todos os mecanismos aqui funcionam de forma assíncrona;
uma requisição que fica bloqueada durante o tempo de uma consulta não é algo que este serviço oferece.
Onde o comportamento é diferente
1. Sem limitador de taxa: use lotes
1. Sem limitador de taxa: use lotes
Não há limite de taxa por chave. Para grandes volumes, use o envio em lote para reduzir as idas e voltas.Veja Regiões e boas práticas.
2. Os créditos são por mecanismo
2. Os créditos são por mecanismo
credits aparece em toda resposta como parte do envelope. As respostas de envio e polling informam
{ "creditsToCharge": 0, "creditsCharged": 0 }; os webhooks informam o custo em créditos do mecanismo (1–3 créditos
conforme o mecanismo).Tarefas com falha não são cobradas. Os saldos de créditos ficam visíveis no painel.3. Alguns pares mecanismo × região são recusados de cara
3. Alguns pares mecanismo × região são recusados de cara
Uma combinação não pode ser atendida de jeito nenhum:
CHATGPT/PERPLEXITY/GEMINI para CN, onde não há oferta de
saída e a requisição nunca chega ao destino. Ela falha imediatamente com 422 REGION_UNSUPPORTED em vez de ser
aceita. 422 REGION_UNAVAILABLE cobre a versão transitória da mesma situação.Um cliente que supõe que todo envio bem formado é aceito precisa de uma ramificação aqui. Veja Regiões.4. As flags include quase não têm efeito
4. As flags include quase não têm efeito
As flags
payload.include são aceitas, mas a maioria dos mecanismos retorna uma resposta de formato fixo e as ignora.
Só o ChatGPT respeita o conjunto completo; GEMINI respeita apenas markdown e rawResponse.Pedir html ao Gemini, por exemplo, é ignorado em silêncio: sem erro e sem campo. Veja a
tabela de flags suportadas.5. Um código de status a mais: 422
5. Um código de status a mais: 422
Fora isso, o tratamento de erros é convencional: falhas de validação retornam
400, 401 informa MISSING_API_KEY,
404 informa RESOURCE_NOT_FOUND e details aponta o campo com problema.A única novidade é o par 422 (REGION_UNSUPPORTED, REGION_UNAVAILABLE) descrito acima. Avisamos de antemão quando
uma região não pode ser atendida, então um cliente que nunca precisou tratar um 422 vai começar a vê-los.6. Uma tarefa com falha ganha uma string error de nível superior
6. Uma tarefa com falha ganha uma string error de nível superior
GET /v1/async/task/{id} em uma tarefa FAILED retorna um campo error de nível superior que o esquema de status da
tarefa não define, e ele é uma string simples, não o objeto {code, message, timestamp} dos erros de requisição.body.error verdadeiro como requisição com falha vai interpretar errado uma tarefa com
falha que foi obtida com sucesso. Ramifique por task.status.Esses comportamentos foram verificados chamando esta API, não lendo um esquema. Se uma especificação publicada e uma
resposta real divergirem, estas páginas documentam a resposta real.
Escolhendo o taskType certo
Se sua integração atual chama um endpoint por mecanismo, o nome do mecanismo corresponde a um taskType:
GOOGLE significar “AI Overview” é uma convenção de nomes, não um nome de produto do Google. A resposta é um
envelope de SERP com aioverview como membro anulável; veja o formato do GOOGLE.Validando a virada
Rode sua integração atual e esta em paralelo por um tempo e compare os campos que você realmente consome, na práticaresponse.text, response.sources[] e response.markdown. Uma comparação em sombra pega diferenças de formato que
uma checagem de esquema não pega, como uma lista de fontes preenchida mas em outra ordem.