↓
Documentação da Rivya AI

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; leia error e 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 succeeded ou failed

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.

Páginas Relacionadas