Guias

Início rápido

Crie uma Task assíncrona e gerencie polling, conclusão, falha e callbacks.

O RunAPI usa Tasks para geração assíncrona de imagens, vídeos, áudios e músicas. Uma requisição de criação retorna rapidamente; sua aplicação então faz polling na Task ou recebe os eventos de callback listados na Referência da API do endpoint.

Criar uma Task

Escolha um modelo e um endpoint no Catálogo e envie os dados de entrada necessários para o endpoint. Este exemplo inicia uma Task de texto para imagem com o Flux 2:

SHELL

curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "A product photograph on a clean studio background"
  }'

Uma requisição assíncrona aceita retorna 202 Accepted com um identificador de Tarefa:

JSON

{
  "id": "task_id",
  "status": "processing"
}

Armazene id com o registro da sua aplicação. É o identificador estável usado para polling, suporte e reconciliação de callbacks.

Evitar criação duplicada de Tarefas

Os endpoints de criação de tarefas aceitam um cabeçalho opcional Idempotency-Key com um valor opaco de até 512 caracteres. Gere um valor para cada tarefa lógica e mantenha-o junto à requisição até confirmar se ela foi aceita.

Se um timeout ou falha de conexão deixar o resultado desconhecido, repita exatamente a mesma requisição de criação de Task com a mesma chave. O RunAPI retorna a Task original em vez de criar e cobrar por uma segunda. Reutilizar uma chave com uma requisição de criação de Task diferente retorna 409 Conflict. Gere uma nova chave para uma Task intencionalmente nova, e não use X-Client-Request-Id como essa chave.

Recuperar uma solicitação síncrona interrompida

Endpoints síncronos lentos normalmente mantêm a conexão aberta e retornam a mesma resposta terminal de antes. Nenhuma alteração de polling é necessária para integrações existentes.

Para um orçamento de conexão intencionalmente mais curto, envie Prefer: wait=N. Se a Task ainda estiver em execução após esse orçamento explícito, o RunAPI retorna 202 Accepted com o mesmo id da Task, uma URL Location opaca para recuperação e Retry-After com o atraso sugerido para a próxima consulta. Siga Location exatamente em vez de construir uma URL de resultado. Um Resultado de Task concluído preserva o status HTTP terminal, os cabeçalhos permitidos, o tipo de conteúdo e o corpo; decodifique response.body de acordo com response.content_type, que nem sempre é JSON.

Consultar uma Tarefa

Acrescente o identificador da Tarefa ao mesmo caminho do endpoint:

SHELL

curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Continue enquanto status for processing. Use backoff limitado entre requisições em vez de realizar polling continuamente. Uma Task se torna terminal quando seu status é completed ou failed.

Tratar conclusão

Uma resposta completed inclui o id da Tarefa, o status terminal e os campos de resultado específicos do endpoint. Persista o resultado necessário e interrompa o polling. Consulte a Referência da API do endpoint para conhecer o formato exato do resultado em vez de presumir que todo endpoint de mídia retorna os mesmos campos.

Tratar falha

Uma resposta failed inclui o id da Tarefa, o status terminal e um error gerado pelo RunAPI, quando disponível. Interrompa o polling, registre o identificador e o erro, e tente novamente somente quando sua aplicação tiver classificado a falha como transitória. Uma nova tentativa cria um novo identificador de Tarefa.

Receber um callback

Adicione um callback_url HTTPS público à requisição de criação quando quiser que o RunAPI envie os eventos de callback documentados para aquele endpoint:

JSON

{
  "model": "flux-2-pro-text-to-image",
  "prompt": "A product photograph on a clean studio background",
  "callback_url": "https://your-domain.com/webhooks/runapi"
}

Cada corpo de callback corresponde a um evento de ciclo de vida na Referência da API do endpoint e omite detalhes de faturamento exclusivos de polling. Callbacks terminais incluem os mesmos campos de resultado que as respostas de polling terminais; alguns endpoints também enviam callbacks processing documentados. Retorne uma resposta HTTP bem-sucedida rapidamente e mantenha o polling disponível para reconciliação quando a entrega estiver atrasada ou seu handler de callback estiver indisponível.

Leia Callbacks para criar um Segredo de Callback, verificar assinaturas e processar novas tentativas com segurança.