Status de Geração
Consulte tarefas de geração da Rivya API pelo ID público, leia os estados `queued`, `processing`, `succeeded` e `failed` e use as URLs de resultado.
Última revisão em 11 de novembro de 2026
Use GET /api/v1/generations/{taskId} para verificar um job de geração assíncrono.
Unidades de prompt e resultados completos de camadas
Leia prompt_length_unit junto com max_prompt_length em GET /api/v1/models. utf8_bytes conta os bytes UTF-8 do texto original, incluindo espaços e quebras de linha; utf16_code_units conta unidades UTF-16 do JavaScript. Um limite null não significa texto ilimitado ou opcional. Gemini TTS usa bytes.
Uma decomposição concluída pode incluir result.layers além da lista completa result.urls. Preserve z_index, URL, tamanho, nome, descrição e caixa delimitadora de cada camada quando fornecidos; o índice zero é a base. O SDK TypeScript expõe esses campos. Envie as referências para o modelo escolhido e repasse os metadados assinados originais; declarar dimensões ou duração não substitui a verificação.
Endpoint
Use o id público retornado ao criar a geração, não o ID do provedor. A consulta verifica a tarefa existente, sem criar outra. Chat usa sessões próprias para resultados e streams; veja Chat API. A chave exige generations:read, API habilitada e uso em HTTPS no servidor. Veja autenticação.
GET https://rivya.ai/api/v1/generations/{taskId}Header obrigatório:
Authorization: Bearer rvya_sk_...Exemplo com curl
curl https://rivya.ai/api/v1/generations/task_public_id \
-H "Authorization: Bearer rvya_sk_..."Valores de Status
queued: há registro, sem resultado final ou falha registrados; não indica posição na fila.processing: tarefa em andamento, incluindo possível fila do serviço.succeeded: resultado bem-sucedido registrado; confira URLs e liquidação separadamente.failed: falha registrada; leiaerrore confira a liquidação.
Os dois primeiros não estimam conclusão. Os dois últimos encerram a geração, mas o sucesso ainda pode exigir conferência de créditos.
Resposta com Sucesso
Modelo, créditos, datas e URL abaixo são ilustrativos, não preço atual, prazo ou saída real para baixar. Em succeeded, result é objeto, mas primary_url pode ser null e urls, vazio. Sucesso não garante arquivo para download. Tarefas de texto expõem URLs, não o texto completo; ausência de URL não indica falha. Nos outros estados, result é null. created_at é criação e updated_at, atualização do registro, não previsão de término.
{
"id": "task_public_id",
"status": "succeeded",
"model": "z-image",
"reserved_credits": 1,
"final_credits": 1,
"settlement_status": "SETTLED",
"created_at": "2026-05-10T00:00:00.000Z",
"updated_at": "2026-05-10T00:01:00.000Z",
"result": {
"primary_url": "https://media.example/result.png",
"urls": ["https://media.example/result.png"]
},
"error": null
}primary_url é a primeira URL de resultado por conveniência. urls contém a lista pública de URLs de resultado quando disponível.
Resposta com Falha
status: failed sempre tem error com code e message; outros estados usam error: null. Esse erro da tarefa é separado de um erro HTTP da consulta. O exemplo confirma falha e reserva devolvida, mas nem toda falha implica débito seguido de devolução: saldo insuficiente pode impedir a dedução. Confira liquidação e transações.
{
"id": "task_public_id",
"status": "failed",
"model": "z-image",
"reserved_credits": 1,
"final_credits": 0,
"settlement_status": "REFUNDED",
"created_at": "2026-05-10T00:00:00.000Z",
"updated_at": "2026-05-10T00:01:00.000Z",
"result": null,
"error": {
"code": "generation_failed",
"message": "The generation failed."
}
}Liquidação de créditos
API e Studio usam o mesmo saldo. Uma geração paga normalmente deduz a reserva antes do envio ao serviço do modelo; atualizar o status também pode atualizar a liquidação.
reserved_credits é a reserva da tarefa, não um preço universal. final_credits é o valor registrado e pode igualar a reserva antes da liquidação. Leia settlement_status: PENDING e RESERVED indicam liquidação pendente; SETTLED indica uso liquidado, com devolução da diferença quando o uso final válido é menor.
RECONCILIATION_REQUIRED indica uso ausente, inválido ou superior à reserva, entre outras pendências. A reserva permanece registrada, sem cobrança automática do excedente; uma consulta posterior pode atualizar a liquidação. REFUNDED confirma a devolução da reserva ao saldo. FAILED significa que não há devolução registrada; é distinto de status: failed e não prova, sozinho, que houve débito.
Espera longa, status inalterado ou erro de consulta não confirmam falha nem devolução. Créditos retornam à conta, não ao cartão. Veja Créditos da API e Tarefas com falha e devoluções.
Orientação de Polling
Após sucesso, pare de consultar o progresso; se a liquidação estiver RECONCILIATION_REQUIRED, confira depois com backoff. Intervalos são sugestões do cliente, não prazo nem garantia de nova consulta ao serviço. O limite de espera não cancela nem prova falha.
Comece com um pequeno atraso e depois aumente os intervalos de consulta. Evite loops apertados.
Padrão recomendado:
aguarde 2 a 3 segundos após o envio
consulte a cada 5 a 10 segundos para jobs normais
diminua o ritmo para jobs longos de vídeo e áudio
pare de consultar quando o status for
succeededoufailed
Status salvo e erros de consulta
Rivya tenta atualizar tarefas elegíveis, mas pode retornar o último status salvo, por exemplo dentro do intervalo de atualização ou sem resposta utilizável do serviço. Sucesso HTTP não garante uma nova consulta ao provedor.
Erro HTTP ou de conexão não fornece um novo status. Preserve o último estado conhecido e repita o mesmo endpoint quando apropriado. Não marque a tarefa como failed nem crie outra geração apenas por falha na consulta. Siga Erros e tentativas da API, guarde o ID e o requestId retornado e não compartilhe a chave.
Limite de Propriedade
A titularidade é por conta, não pela chave original. Outra chave válida da mesma conta pode ler com generations:read e API habilitada. Tarefas inexistentes ou de outra conta retornam HTTP 404 not_found. O catálogo não concede acesso às tarefas.
A tarefa deve pertencer à mesma conta Rivya por trás da chave de API. Se não for encontrada ou não pertencer à conta, o endpoint retornará not_found.
