Fal.ai

Visão geral

Fal.ai é a plataforma de mídia generativa para desenvolvedores, com mais de 600 modelos de IA para geração de imagens, vídeos, voz e áudio. Com a integração Fal.ai no SquadOS, seus agentes podem invocar modelos de geração de conteúdo em tempo real ou de forma assíncrona, fazer upload de arquivos de mídia como entrada, consultar preços de modelos e monitorar o status de jobs em fila — tudo a partir de conversas e fluxos automatizados.

• 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

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

Dica

Crie uma chave dedicada para o SquadOS. Assim, você pode revogar o acesso desta integração sem afetar outras ferramentas ou projetos que usam a mesma conta Fal.ai.

Como conectar no SquadOS

1. Acesse Ferramentas no menu lateral (/admin/tools).
2. Abra a aba Disponíveis e procure por Fal.ai.
3. Clique no card para abrir o modal de detalhes e em Conectar.
4. Você é levado para a página de conexão segura hospedada pela Composio, onde informa a chave de API obtida acima.
5. Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo 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.

Executar modelo (síncrono)

FAL_AI_RUN_MODEL_SYNC

Invoca um modelo do Fal.ai de forma síncrona via fal.run, gerando conteúdo novo (imagens, áudio, vídeo ou outras saídas de modelo) hospedado em URLs da CDN do Fal.ai na resposta. Cada chamada executa inferência paga no Fal.ai — consome o saldo de créditos da conta conectada e é cobrada por requisição, portanto não é uma operação somente leitura. Use quando precisar de um resultado único e o modelo for rápido o suficiente para retornar de forma inline — a requisição bloqueia até o modelo terminar e retorna a saída gerada diretamente. Para jobs de longa duração, invocações paralelas ou uso em produção, prefira SUBMIT_ASYNC_JOB (queue.fal.run), que adiciona persistência, tentativas automáticas e webhooks; ambas produzem o mesmo tipo de saída recém-gerada e hospedada de forma persistente, e são cobradas de forma idêntica.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
input	object	Sim	Payload de entrada específico do modelo, enviado como corpo JSON da requisição. Os campos dependem do modelo escolhido — por exemplo, modelos de geração de imagem normalmente esperam um prompt (e opcionalmente image_size, num_inference_steps, etc.). Consulte o schema OpenAPI do modelo (veja GET_MODELS com expand=openapi-3.0) para a lista completa de campos.
model_id	string	Sim	Identificador do modelo no formato namespace/nome (ex.: fal-ai/flux/schnell, fal-ai/fast-sdxl). As barras no ID do modelo são preservadas no caminho da URL.
runner_hint	string	Não	Dica opcional de afinidade de sessão para rotear requisições subsequentes ao mesmo runner. Enviado como cabeçalho X-Fal-Runner-Hint.
timeout_seconds	integer	Não	Prazo opcional de execução no lado do servidor, em segundos. Enviado como cabeçalho X-Fal-Request-Timeout.

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.

Enviar job de inferência assíncrono

FAL_AI_SUBMIT_ASYNC_JOB

Envia um job de inferência assíncrono para a fila do Fal.ai (queue.fal.run). Use quando quiser executar um modelo sem bloquear — o Fal.ai persiste a requisição, escala runners automaticamente, e você busca o resultado posteriormente via request_id retornado (use QUEUE_GET_STATUS para monitorar, GET_QUEUE_REQUEST_RESULT para recuperar, CANCEL_QUEUE_REQUEST para cancelar e QUEUE_GET_STATUS_STREAM para receber atualizações via SSE). Suporta um webhook_url opcional para o qual o Fal.ai enviará os resultados via POST ao concluir.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
input	object	Sim	Payload de entrada específico do modelo, enviado como corpo JSON da requisição. Os campos dependem do modelo escolhido — por exemplo, modelos de geração de imagem normalmente esperam um prompt (e opcionalmente image_size, num_inference_steps, etc.). Consulte o schema OpenAPI do modelo (veja GET_MODELS com expand=openapi-3.0) para a lista completa de campos.
model_id	string	Sim	Identificador do modelo no formato namespace/nome (ex.: fal-ai/flux/schnell, fal-ai/fast-sdxl). As barras no ID do modelo são preservadas no caminho da URL.
no_retry	boolean	Não	Defina como true para desativar as tentativas automáticas do Fal.ai em caso de erros transitórios do runner. Enviado como cabeçalho X-Fal-No-Retry quando verdadeiro.
priority	string ("normal" | "low")	Não	Dica opcional de prioridade de fila. Enviado como cabeçalho X-Fal-Queue-Priority.
runner_hint	string	Não	Dica opcional de afinidade de sessão para rotear requisições subsequentes ao mesmo runner. Enviado como cabeçalho X-Fal-Runner-Hint.
webhook_url	string	Não	URL opcional para receber um callback via POST quando o job for concluído. Enviado ao Fal.ai como parâmetro de consulta fal_webhook.
timeout_seconds	integer	Não	Prazo opcional de execução no lado do servidor, em segundos. Enviado como cabeçalho X-Fal-Request-Timeout.

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.

Aguardar conclusão de job assíncrono

FAL_AI_SUBSCRIBE_ASYNC_JOB

Envia um job de inferência do Fal.ai para a fila assíncrona e bloqueia até a conclusão (ou até atingir um prazo limite), retornando o resultado final do modelo. Reproduz a ergonomia do subscribe() do fal-js: SUBMIT_ASYNC_JOB + polling com QUEUE_GET_STATUS + GET_QUEUE_REQUEST_RESULT em uma única chamada. Use quando quiser a confiabilidade do modo assíncrono (persistência de fila, tentativas automáticas) com um valor de retorno síncrono, e o modelo for rápido o suficiente para terminar dentro de max_wait_seconds. Para jobs muito longos, prefira SUBMIT_ASYNC_JOB e verifique o status/resultado manualmente ou via webhook.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
input	object	Sim	Payload de entrada específico do modelo, enviado como corpo JSON da requisição.
model_id	string	Sim	Identificador do modelo no formato namespace/nome (ex.: fal-ai/flux/schnell). As barras são preservadas no caminho da URL.
priority	string ("normal" | "low")	Não	Dica opcional de prioridade de fila para o envio inicial (X-Fal-Queue-Priority).
runner_hint	string	Não	Dica opcional de afinidade de sessão para o envio inicial (X-Fal-Runner-Hint).
include_logs	boolean	Não	Se true, solicita logs do runner a cada polling de status (encaminhado ao Fal.ai como ?logs=1).
timeout_seconds	integer	Não	Prazo opcional de execução no lado do servidor, em segundos, para o envio inicial (X-Fal-Request-Timeout).
max_wait_seconds	number	Não	Prazo máximo. Se o job não mudar para COMPLETED dentro desse número de segundos, a ação lança um erro de timeout (o job subjacente não é cancelado). Limitado a 900 para manter a ação dentro dos limites de execução serverless da Composio.
poll_interval_seconds	number	Não	Segundos entre os polls de status enquanto o job está em IN_QUEUE ou IN_PROGRESS.

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.

Fazer upload de arquivo de entrada

FAL_AI_UPLOAD_FILE

Faz o upload de um arquivo de mídia de entrada (imagem, áudio ou vídeo) para a CDN do Fal.ai e retorna uma access_url pública que pode ser passada como entrada de modelo. Muitos modelos do Fal.ai aceitam uma URL para entradas como image_url, audio_url ou video_url — use esta ação primeiro para hospedar o arquivo e, em seguida, passe a access_url para RUN_MODEL_SYNC ou SUBMIT_ASYNC_JOB. Internamente, realiza o upload em dois passos do Fal.ai: (1) POST para rest.fal.ai/storage/upload/initiate para obter uma URL de upload pré-assinada; (2) PUT dos bytes para essa URL.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
file	object	Sim	Arquivo a fazer upload para o armazenamento do Fal.ai. A access_url retornada pode ser passada como campo de entrada de modelo (ex.: image_url, audio_url, video_url). Tipos suportados incluem imagens (jpg, jpeg, png, gif, webp), vídeos (mp4, mov, webm) e áudio (mp3, wav, flac).

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.