Groq icon

Groq

Use Groq models via the AI SDK
Join our community

Actions2

Overview

This node integrates with Groq AI models via the AI SDK to generate text or structured objects based on user input. It supports two main operations:

  • Generate Text: Produces text completions from either a simple prompt or a conversation consisting of multiple messages.
  • Generate Object: Generates structured data conforming to a user-defined JSON schema, useful for extracting specific information or creating typed outputs.

Common scenarios include:

  • Generating conversational responses or content completions using prompts or chat-style messages.
  • Extracting structured insights such as sentiment analysis, entity extraction, or custom data formats by defining a JSON schema.
  • Automating data transformation workflows where AI-generated structured data is required.

Practical examples:

  • Using a single prompt to generate a product description.
  • Feeding a conversation history to generate a chatbot reply.
  • Defining a JSON schema for sentiment and score, then generating an object that classifies customer feedback.

Properties

Name Meaning
Model Name or ID Select the Groq model to use from a list or specify an ID via expression.
Operation Choose between "Generate Text" (text completion) or "Generate Object" (structured output based on JSON schema).
Input Type Select how to provide input: "Simple Prompt" (single text prompt) or "Messages" (multiple chat messages).
System Optional system prompt guiding the model's behavior when using Simple Prompt input type. Defaults to "You are a helpful assistant."
Prompt The single text prompt to generate a completion for (required if Input Type is Simple Prompt).
Messages A collection of messages forming a conversation, each with a role (system, user, assistant) and content. Used if Input Type is Messages and not using JSON input.
Messages as JSON Boolean flag to input messages as a JSON array string instead of UI fields (only for Messages input type).
Messages (JSON) JSON string representing an array of message objects with role and content properties. Required if Messages as JSON is true.
Schema Name Optional name of the output JSON schema, used as additional guidance for some providers (only for Generate Object operation).
Schema Description Optional description of the output JSON schema, providing further guidance (only for Generate Object operation).
Schema JSON schema describing the structure of the object to generate. Must be valid JSON and conform to JSON Schema standards. Example provided describes sentiment analysis output. (only for Generate Object operation)
Options Collection of optional parameters:
- Max Tokens: maximum tokens to generate.
- Temperature: randomness of output (0 to 2).
- Include Request Body: whether to include the request body in the output for debugging.

Output

The node outputs an array of items, each containing a json field with the result of the generation:

  • For Generate Text:

    • text: The generated text completion.
    • reasoning: Optional extracted reasoning if present in the response.
    • finishReason: Reason why generation stopped.
    • usage: Token usage statistics including prompt, completion, and total tokens.
    • cacheMetrics: Cache hit/miss token counts if available.
    • response: Metadata about the API response (id, modelId, timestamp, headers).
    • warnings: Any warnings returned by the API.
    • Optionally, if enabled, the original request body sent to the API.

  • For Generate Object:

    • object: The generated structured object matching the provided JSON schema.
    • finishReason, usage, response, warnings: Same metadata fields as above.
    • Optionally, the original request body if requested.

The node does not output binary data.

Dependencies

  • Requires an external Groq API service accessible via an API key credential.
  • The API key must be configured in n8n credentials for this node to authenticate requests.
  • Uses the AI SDK (@ai-sdk/groq and ai packages) internally to interact with the Groq models.
  • Validates JSON schemas using the ajv library.

Troubleshooting

  • Missing API Key: If no API key is provided in credentials, the node will throw an error indicating the missing key. Ensure the Groq API key credential is properly set up.
  • Invalid JSON in Messages (JSON): When using JSON input for messages, invalid JSON syntax or incorrect structure will cause an error. Validate the JSON format and ensure it is an array of objects with role and content.
  • Invalid JSON Schema: For Generate Object operation, if the provided schema is not valid JSON or fails JSON Schema validation, the node throws an error. Use a JSON validator and ensure compliance with JSON Schema standards.
  • API Errors: Network issues or invalid model IDs may cause request failures. Check API connectivity and model availability.
  • Continue On Fail: If enabled, errors per item will be captured in the output rather than stopping execution.

Links and References

Discussion