Fal.ai

Visão geral

Fal.ai é uma plataforma de mídia generativa para desenvolvedores. No export local mais recente do catálogo do SquadOS, esta integração oferece descoberta e preço de modelos, chaves para verificar webhooks e operações para consultar, acompanhar ou cancelar requisições de fila já existentes. O export não inclui uma ação para iniciar inferência ou enviar arquivos; portanto, esta página não promete geração de mídia pelo agente no estado documentado.

Site oficial: https://fal.ai/
Documentação na Composio: docs.composio.dev/toolkits/fal_ai

Autenticação

Esta ferramenta utiliza chave de API (API_KEY) para conectar.

Você vai precisar dos seguintes campos:

Campo	Obrigatório	Descrição
`api_key`	Sim	Chave de API gerada no painel Fal.ai, usada para autenticar todas as requisições de inferência e gestão de fila.

Como obter a credencial

Acesse fal.ai/login e crie uma conta ou faça login com GitHub ou Google.
No menu lateral esquerdo do painel, clique em API Keys (ou acesse diretamente fal.ai/dashboard/keys).
Clique em Add Key.
Dê um nome à chave (ex.: squados) e clique em Create Key.
Copie a chave gerada e guarde-a em local seguro — ela não será exibida novamente.

Como conectar no SquadOS

Acesse Ferramentas no menu lateral (/admin/tools).
Abra a aba Disponíveis e procure por Fal.ai.
Abra o card em Configurar ferramenta e selecione Ativar. A integração passa para Ativas como Aguardando autenticação.
Abra a integração ativa, selecione Conectar agora e informe a chave na página segura hospedada pela Composio.
Ao retornar ao SquadOS, confirme em Contas que a conta está ativa.
Revise Editar ações; depois adicione Fal.ai pela seção Ferramentas do agente, escolha a conta e as ações, salve e faça um teste seguro.

Ativação, autenticação e vínculo com o agente são etapas separadas. Veja o contrato completo em Ferramentas da Organização.

Ações disponíveis

Cancelar requisição na fila

FAL_AI_CANCEL_QUEUE_REQUEST

Cancela uma requisição enfileirada ou em andamento no sistema de fila do Fal.ai. Use quando precisar interromper uma requisição antes de ela ser concluída. Observe que o cancelamento só tem efeito se a requisição ainda não tiver iniciado o processamento; se já foi concluída, retorna um status de erro. Mesmo com cancelamento bem-sucedido, a requisição ainda pode ser executada se estiver próxima do início da fila.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`model_id`	string	Sim	Identificador do modelo no formato namespace/nome (ex.: `fal-ai/flux`, `fal-ai/fast-sdxl`).
`request_id`	string	Sim	Identificador único da requisição enfileirada a ser cancelada.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Estimar preço

FAL_AI_ESTIMATE_PRICING

Estima o custo de chamadas a endpoints de modelos do Fal.ai. Use quando precisar calcular os custos esperados para chamadas de API ou uso baseado em unidades em um ou mais endpoints.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`endpoints`	object	Sim	Mapa de IDs de endpoints (ex.: `fal-ai/flux/dev`) para suas especificações de quantidade. Use `call_quantity` para `historical_api_price` ou `unit_quantity` para `unit_price`.
`estimate_type`	string (`"historical_api_price"` \| `"unit_price"`)	Sim	Método de estimativa: `historical_api_price` para estimativas baseadas em chamadas ou `unit_price` para estimativas baseadas em unidades.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter chaves JWKS para verificação de webhook

FAL_AI_GET_JWKS

Recupera as chaves públicas para verificação de assinatura de webhooks. Retorna um JSON Web Key Set contendo chaves públicas ED25519. Use quando precisar verificar assinaturas de webhooks enviados pelo Fal.ai. As chaves podem ser armazenadas em cache, mas devem ser atualizadas pelo menos a cada 24 horas.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar modelos

FAL_AI_GET_MODELS

Descobre e pesquisa endpoints de modelos do Fal.ai. Use quando precisar listar todos os modelos, encontrar modelos específicos por ID ou pesquisar por categoria ou consulta de texto. Suporta paginação e expansão opcional de schemas OpenAPI.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`q`	string	Não	Consulta de texto livre. Filtra modelos por nome, descrição ou categoria. Use para pesquisas amplas baseadas em texto.
`limit`	integer	Não	Número máximo de itens a retornar. O máximo real depende do tipo de consulta.
`cursor`	string	Não	Cursor de paginação da resposta anterior. Codifica o número da página para buscar a próxima.
`expand`	string	Não	Campos a expandir na resposta. Suporta `openapi-3.0` para incluir o schema OpenAPI completo de cada modelo.
`status`	string (`"active"` \| `"deprecated"`)	Não	Filtra modelos por status. Use `active` para modelos atualmente suportados ou `deprecated` para modelos obsoletos. Omita para incluir todos os status.
`category`	string	Não	Filtra modelos por categoria específica. Use nomes exatos como `text-to-image`, `image-to-video`, etc.
`endpoint_id`	string	Não	ID(s) de endpoint específico(s) a recuperar. Aceita uma string única ou array de strings (1 a 50 modelos). Use para filtrar modelos por seus identificadores únicos.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Consultar preço de modelo

FAL_AI_GET_PRICING

Recupera o preço unitário de endpoints de modelos. Retorna informações de precificação incluindo preço por unidade, unidade de cobrança e moeda. Use quando precisar verificar os custos de modelos específicos do Fal.ai.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`endpoint_id`	string	Sim	Filtra por ID(s) de endpoint específico(s). Aceita de 1 a 50 IDs de endpoint. Pode ser uma string com um único ID ou uma lista de IDs. Exemplos: `fal-ai/flux/dev` ou `['fal-ai/flux/dev', 'fal-ai/flux/pro']`.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter resultado de requisição na fila

FAL_AI_GET_QUEUE_REQUEST_RESULT

Recupera o resultado final de uma requisição concluída na fila. Use quando precisar obter a saída de uma requisição enviada à fila que já terminou o processamento. Funciona apenas após o status da requisição mudar para COMPLETED.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`model_id`	string	Sim	Identificador do modelo no formato namespace/nome (ex.: `fal-ai/flux`, `fal-ai/fast-sdxl`).
`request_id`	string	Sim	Identificador único da requisição enfileirada da qual se deseja recuperar os resultados.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Verificar status de requisição na fila

FAL_AI_QUEUE_GET_STATUS

Verifica o status de uma requisição enfileirada no Fal.ai. Use quando precisar monitorar o andamento de uma requisição assíncrona. Retorna informações diferentes conforme o status: posição na fila quando IN_QUEUE, logs quando IN_PROGRESS ou COMPLETED.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`logs`	integer	Não	Defina como `1` para habilitar a recuperação de logs na resposta; desativado por padrão para melhorar a performance.
`model_id`	string	Sim	Identificador do modelo no formato namespace/nome (ex.: `fal-ai/fast-sdxl`).
`request_id`	string	Sim	Identificador único retornado após o envio de uma requisição.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Transmitir atualizações de status via SSE

FAL_AI_QUEUE_GET_STATUS_STREAM

Transmite atualizações de status de uma requisição via SSE (Server-Sent Events). Use quando precisar de atualizações em tempo real sobre o estado de processamento de uma requisição enfileirada.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`logs`	integer	Não	Defina como `1` para incluir informações detalhadas de logging no stream; omita ou use `0` para excluir logs.
`model_id`	string	Sim	Identificador do modelo (ex.: `fal-ai/fast-lightning-sdxl`).
`request_id`	string	Sim	Identificador único retornado ao enviar uma requisição.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Usar o catálogo com segurança

As ações atuais permitem descobrir modelos e preços, verificar chaves de webhook e acompanhar ou cancelar requisições de fila já existentes. Antes de configurar uma ação, abra seu schema no editor do agente e copie exatamente os campos, tipos e obrigatoriedade exibidos. O checkout não contém esses schemas completos, e a auditoria não consultou banco nem produção.

Consultar preços não reserva saldo. Cancelar uma requisição pode falhar se o processamento já começou e não garante estorno. Trate IDs de modelo e de requisição como dados externos e teste somente com uma conta e um orçamento controlados.