Skip to main content
Version: 2026.1

OpenAI-Compatible Text Generation

This document covers the OpenAI-compatible text generation automation action step available in Pimcore Copilot.

Overview​

The OpenAI-compatible text generation step (generic_openai_compatible_text_generation) enables you to generate text content using any OpenAI-compatible API, including OpenAI, Azure OpenAI, Anthropic Claude, local models, and other providers that implement the OpenAI chat completions format.

The step supports dynamic prompt templating using Twig syntax and can save generated text to object fields or execution context.

Features​

Prompt Templating​

The text generation step supports Twig templating with access to the current subject:

prompt_template: |
  Generate a product description for {{ subject.name }}.
  Category: {{ subject.category }}
  Price: {{ subject.price }}

Output Configuration​

Generated text can be saved to:

  • Subject fields: Save directly to the current object's field
  • Execution context: Store for use in subsequent automation steps
output_targets:
  save_on_subject: true
  save_on_execution_context: false

Configuration​

steps:
  - step_implementation: 'generic_openai_compatible_text_generation'
    name: 'Generate Content with OpenAI'
    configuration:
      endpoint: 'https://api.openai.com/v1/chat/completions'
      api_key: 'sk-your-openai-api-key'
      model: 'gpt-3.5-turbo'
      prompt_template: |
        Write engaging marketing copy for {{ subject.name }}.
        Target audience: {{ subject.targetAudience }}
        Tone: Professional and friendly
      output_field: 'marketingCopy'
      language: 'en'
      output_targets:
        save_on_subject: true
        save_on_execution_context: false
      parameters:
        temperature: 0.7
        max_tokens: 500
        top_p: 1.0

Required Configuration​

  • endpoint: API endpoint URL
  • model: Model identifier
  • prompt_template: Twig template for the prompt
  • output_field: Field name to save the generated text

Optional Configuration​

  • api_key: API authentication key that may be needed to use the configured endpoint
  • language: Language code for localized fields
  • parameters: OpenAI API parameters
    • temperature: Randomness (0.0-2.0)
    • max_tokens: Maximum response length
    • top_p: Nucleus sampling parameter
    • frequency_penalty: Reduce repetition (-2.0 to 2.0)
    • presence_penalty: Encourage new topics (-2.0 to 2.0)
    • stop: Stop sequences (string or array)

Supported Providers​

The OpenAI-compatible step works with any provider that implements the OpenAI chat completions API format:

OpenAI​

endpoint: 'https://api.openai.com/v1/chat/completions'
model: 'gpt-4o'  # or gpt-4, gpt-4-turbo, etc.

HuggingFace Inference Endpoints​

endpoint: 'https://router.huggingface.co/{inference_provider}/v1/chat/completions'
model: '<your_model>'

Error Handling​

The step includes comprehensive error handling:

  • API errors: Logged with response details
  • Empty responses: Detected and logged
  • Template errors: Twig syntax errors are caught
  • Field validation: Output field availability is verified

Error messages are logged to the job run with context including:

  • Subject path
  • Error details
  • Generated text length (on success)

Best Practices​

Prompt Design​

  • Be specific and clear in your prompts
  • Include relevant context from the subject
  • Use consistent formatting
  • Test prompts with sample data

Model Selection​

  • OpenAI-compatible: Balance cost, speed, and quality
  • Local models: Consider latency and resource requirements

Performance​

  • Batch similar requests when possible
  • Monitor API rate limits and costs

Security​

  • Store API keys as environment variables
  • Use least-privilege API keys
  • Monitor API usage for unexpected spikes

Troubleshooting​

Common Issues​

  1. Empty responses: Check model endpoint and API key
  2. Rate limiting: Implement delays or use different models
  3. Template errors: Validate Twig syntax and subject field access
  4. Field not found: Ensure output field exists in object class definition

Debug Tips​

  • Check job run logs for detailed error messages
  • Test API endpoints manually with curl
  • Verify environment variable resolution
  • Use simple prompts first, then add complexity