The ai command uses OpenAI’s language models to generate service definitions from natural language descriptions.
Prerequisites You must set the OPENAI_API_KEY environment variable:
export OPENAI_API_KEY = sk- ...
The AI command requires a valid OpenAI API key. You’ll receive a 401 error if the key is missing or invalid.
generate Generate a service definition from a natural language prompt.
apicentric ai generate --prompt < descriptio n >
Natural language description of the API service you want to create
Usage examples Simple REST API apicentric ai generate --prompt "Create a user management API with CRUD endpoints"
E-commerce API apicentric ai generate --prompt "Build an e-commerce API with products, cart, and checkout endpoints"
Specific requirements apicentric ai generate --prompt "Create a blog API with posts, comments, and authors. Include pagination and filtering."
How it works
Prompt processing : Your description is sent to OpenAI’s APIService generation : The AI generates a complete service definition in YAML formatAuto-apply : If the simulator is running, the service is automatically appliedOutput : The generated YAML is displayed or applied to the simulator
Output behavior With simulator running The generated service is automatically applied:
$ apicentric ai generate --prompt "user API with login and registration" 🤖 Generating service from: "user API with login and registration"... ✅ Generated service 'users' applied to simulator
Without simulator The YAML is printed to stdout:
$ apicentric ai generate --prompt "simple todo API" 🤖 Generating service from: "simple todo API"... name: todos version: 1.0.0 server: port: 9001 base_path: / endpoints: - path: /todos method: GET ...
Error handling Missing API key ❌ Authentication Failed: Missing or invalid OPENAI_API_KEY 👉 Please set the OPENAI_API_KEY environment variable to use AI features. Example: export OPENAI_API_KEY=sk-...
Generation failure ❌ AI Generation Failed: <error details>
Best practices
Be specific Include details about endpoints, data models, and behavior
Use examples Mention specific endpoints or data structures you need
Iterate Generate, review, and refine your prompts for better results
Combine with editing Use generated services as a starting point and manually refine them
Dry run mode Test the command without making API calls:
apicentric --dry-run ai generate --prompt "user API"
Output:
🏃 Dry run: Would generate service from prompt: user API
Tips for better results Good prompts # Detailed with structure apicentric ai generate --prompt "Create a task management API with users, projects, and tasks. Include authentication endpoints." # Specific data models apicentric ai generate --prompt "Build a book API where books have title, author, ISBN, and publication year" # Include behaviors apicentric ai generate --prompt "Create a weather API with endpoints for current weather and 5-day forecast, including error scenarios"
Prompts to avoid # Too vague apicentric ai generate --prompt "API" # Conflicting requirements apicentric ai generate --prompt "Create both a REST and GraphQL service"
Next steps
Save generated YAML to a file: apicentric ai generate --prompt "..." > service.yaml
Edit generated services with apicentric simulator edit
Start the simulator with apicentric simulator start