Skip to content
Last updated

Prompt Templates

Prompt templates are reusable, version-controlled prompts that let you define instructions once and apply them consistently across multiple API calls with dynamic variable substitution.

Why Use Prompt Templates?

Consistency: Ensure the same instructions are used across your application without copy-pasting prompts.

Version Control: Track changes to prompts over time and roll back if needed.

Dynamic Content: Inject variables like user names, dates, or context into standardized prompts.

Team Collaboration: Share and manage prompts across team members.

A/B Testing: Test different prompt versions to optimize model performance.

How Prompt Templates Work

  1. Create a template with placeholder variables (e.g., {{user_name}}, {{task}})
  2. Save and version the template in your Freddy Hub
  3. Reference the template by ID in your API calls
  4. Pass variables to substitute into the placeholders
  5. Model receives the complete prompt with variables filled in

Creating a Prompt Template

Via Freddy Hub

  1. Go to Freddy Hub
  2. Click "Create Prompt Template"
  3. Define your prompt with variables:
You are an expert {{role}}. 
Help the user with: {{task}}

User context:
- Name: {{user_name}}
- Experience level: {{experience_level}}

Provide a {{tone}} response with {{detail_level}} detail.
  1. Save the template - you'll receive a template ID like prompt_abc123

Template Variables

Variables use double curly braces: {{variable_name}}

Supported variable types:

  • Strings: Text values
  • Numbers: Numeric values
  • Images: File IDs or URLs
  • Files: Document file IDs
  • Arrays: Lists of values

Using Prompt Templates

Basic Usage

curl https://api.freddy.aitronos.com/v1/model/response \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "prompt": {
      "id": "prompt_abc123",
      "variables": {
        "role": "Python developer",
        "task": "debugging code",
        "user_name": "Alice",
        "experience_level": "intermediate",
        "tone": "friendly",
        "detail_level": "comprehensive"
      }
    },
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "My code keeps throwing a TypeError"}]
      }
    ]
  }'

With Versioning

import requests

response = requests.post(
    "https://api.freddy.aitronos.com/v1/model/response",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "gpt-4.1",
        "prompt": {
            "id": "prompt_abc123",
            "version": "v2.1",  # Use specific version
            "variables": {
                "customer_name": "John Doe",
                "issue_type": "billing"
            }
        },
        "inputs": [
            {"role": "user", "texts": [{"text": "I was charged twice"}]}
        ]
    }
)

Dynamic Variables

// Customer support example
const createSupportResponse = async (customerId, issueDescription) => {
  // Fetch customer data
  const customer = await getCustomer(customerId);
  
  const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'gpt-4.1',
      prompt: {
        id: 'prompt_support_agent',
        variables: {
          customer_name: customer.name,
          account_type: customer.tier,
          issue_category: classifyIssue(issueDescription),
          response_urgency: customer.tier === 'premium' ? 'high' : 'standard'
        }
      },
      inputs: [
        {
          role: 'user',
          texts: [{ text: issueDescription }]
        }
      ]
    })
  });
  
  return await response.json();
};

Template Versioning

Why Version Templates?

  • Experiment safely: Test new prompts without affecting production
  • Rollback capability: Revert to previous versions if needed
  • Track performance: Compare results across prompt iterations
  • Gradual rollout: Deploy new prompts to subset of users first

Version Naming

v1.0    - Initial production version
v1.1    - Minor improvements
v2.0    - Major prompt restructure
latest  - Always points to newest version (default)

Specifying Versions

{
  "prompt": {
    "id": "prompt_abc123",
    "version": "v1.0"  // Pin to specific version
  }
}

Omit version to always use the latest:

{
  "prompt": {
    "id": "prompt_abc123"
    // No version = uses latest
  }
}

Advanced Use Cases

Multi-Language Support

{
  "prompt": {
    "id": "prompt_multilang_support",
    "variables": {
      "language": "Spanish",
      "user_query": "¿Cómo funciona esto?"
    }
  }
}

Template content:

Respond in {{language}}. 
User asks: {{user_query}}

Image Analysis with Templates

{
  "prompt": {
    "id": "prompt_image_analyzer",
    "variables": {
      "analysis_focus": "safety concerns",
      "detail_level": "comprehensive",
      "target_image": "file_img123"
    }
  },
  "inputs": [
    {
      "role": "user",
      "texts": [{"text": "Analyze this image"}],
      "images": [{"fileId": "file_img123"}]
    }
  ]
}

Code Review Template

{
  "prompt": {
    "id": "prompt_code_reviewer",
    "variables": {
      "language": "Python",
      "review_focus": ["performance", "security", "best practices"],
      "experience_level": "senior"
    }
  }
}

Best Practices

✅ DO

  • Use descriptive variable names: {{customer_name}} not {{name}}
  • Version major changes: Increment version for significant prompt rewrites
  • Test templates: Validate with sample data before production use
  • Document templates: Add descriptions explaining purpose and variables
  • Set defaults: Provide fallback values for optional variables
  • Pin versions in production: Use specific versions for critical workflows

❌ DON'T

  • Hardcode sensitive data: Never put API keys or secrets in templates
  • Over-complicate: Keep templates focused and maintainable
  • Ignore versioning: Always version templates for production use
  • Mix concerns: One template should have one clear purpose
  • Skip validation: Always test variable substitution

Template Management

Listing Templates

curl https://api.freddy.aitronos.com/v1/prompts \
  -H "Authorization: Bearer $FREDDY_API_KEY"

Updating Templates

Templates are immutable once created. To update:

  1. Create a new version in Freddy Hub
  2. Test the new version
  3. Update your code to use the new version
  4. Deprecate old versions

Deleting Templates

curl https://api.freddy.aitronos.com/v1/prompts/prompt_abc123 \
  -X DELETE \
  -H "Authorization: Bearer $FREDDY_API_KEY"

Note: Deleting a template affects all code using it. Prefer deprecation over deletion.

Template vs Inputs

When to use Prompt Templates:

  • Standardized workflows (customer support, code review)
  • Team-shared prompts
  • A/B testing different prompts
  • Version-controlled instructions

When to use direct Inputs:

  • One-off requests
  • Highly dynamic, unique prompts
  • Rapid prototyping
  • User-generated prompts

You can also combine both:

{
  "model": "gpt-4.1",
  "prompt": {
    "id": "prompt_base_instructions",
    "variables": {"expertise": "medical"}
  },
  "inputs": [
    {
      "role": "user",
      "texts": [{"text": "What causes headaches?"}]
    }
  ]
}

The template provides base instructions, while inputs add the specific user query.

Troubleshooting

Missing Variables

If a template requires variables you don't provide:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required template variable: 'user_name'",
    "code": "missing_template_variable",
    "param": "prompt.variables.user_name"
  }
}

Template Not Found

{
  "error": {
    "type": "invalid_request_error",
    "message": "Prompt template not found",
    "code": "template_not_found",
    "param": "prompt.id"
  }
}

Version Not Found

{
  "error": {
    "type": "invalid_request_error",
    "message": "Prompt template version 'v99.0' not found",
    "code": "template_version_not_found",
    "param": "prompt.version"
  }
}

Related:

Previous page
Next page