# 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](https://freddy-hub.aitronos.com/freddy/prompts) 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 ```bash 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 ```python 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 ```javascript // 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 ```json { "prompt": { "id": "prompt_abc123", "version": "v1.0" // Pin to specific version } } ``` **Omit `version`** to always use the latest: ```json { "prompt": { "id": "prompt_abc123" // No version = uses latest } } ``` ## Advanced Use Cases ### Multi-Language Support ```json { "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 ```json { "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 ```json { "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 ```bash 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 ```bash 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**: ```json { "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: ```json { "error": { "type": "invalid_request_error", "message": "Missing required template variable: 'user_name'", "code": "missing_template_variable", "param": "prompt.variables.user_name" } } ``` ### Template Not Found ```json { "error": { "type": "invalid_request_error", "message": "Prompt template not found", "code": "template_not_found", "param": "prompt.id" } } ``` ### Version Not Found ```json { "error": { "type": "invalid_request_error", "message": "Prompt template version 'v99.0' not found", "code": "template_version_not_found", "param": "prompt.version" } } ``` **Related:** - [Create Model Response](/docs/api-reference/responses/create) - [Text Generation](/docs/documentation/core-concepts/text-generation) - [Best Practices](/docs/documentation/best-practices)