Gen3 Gt Api Runbooks Dify - GT-Edge-AI/GT-AI-OS GitHub Wiki

Start Here

Add an OpenAI-API-compatible model provider in Dify pointed at GT API for chat and embeddings; implement GT upload and conversation routes as explicit HTTP workflow steps. Recommended preset: Chat plus embeddings framework client.

Why this matters

This runbook maps Dify to GT API routes operators actually publish.

Details

Compatibility: OpenAI plus GT extensions ยท Category: Workflow and builders

Official documentation

Configuration fields

  • OpenAI-API-compatible โ†’ API Base URL: https://<tenant-host>/api/tenant
  • OpenAI-API-compatible โ†’ API Key: gtak_...
  • LLM node โ†’ Model (published alias): published-agent-alias

GT route mapping

GT route Verdict Client integration
GET /v1/models native Dify provider test + manual GET /v1/models during provider setup
POST /v1/chat/completions native App/workflow LLM node โ†’ /v1/chat/completions via OpenAI-compatible provider
POST /v1/embeddings native Embedding model selection through same provider โ†’ /v1/embeddings
POST /v1/audio/transcriptions not_supported Not exposed through Dify OpenAI-compatible provider by default
POST /v1/audio/speech not_supported Not exposed through Dify OpenAI-compatible provider by default
POST /v1/images/generations not_supported Requires image-capable published target and GT image scope if used
POST /v1/conversations/files gt_extension Workflow HTTP Request multipart with GT conversation header
POST /v1/datasets/{id}/files gt_extension Workflow HTTP Request to dataset files route
GET /v1/files/{id} gt_extension Workflow HTTP GET poll on file id

Not supported in this product

  • Dify vendor-native OpenAI file and assistant APIs do not map to GT dataset or conversation upload semantics.

Prerequisites

  • Publish aliases for Dify apps and workflows.
  • Grant inference:chat and inference:embed on key when knowledge/RAG uses GT embeddings.

Setup steps

  1. Dify console โ†’ Model Provider โ†’ OpenAI-API-compatible โ†’ set Base URL to tenant GT API.
  2. Paste GT API key and save provider credentials.
  3. Select a published alias in an app LLM node; run test completion.
  4. Add HTTP Request node in workflows for GT conversation bootstrap or dataset uploads when required.

GT extensions and caveats

  • Call POST /v1/conversations from a workflow tool you control, not from default OpenAI provider shortcuts.
  • Use /v1/datasets/{id}/files from HTTP nodes โ€” Dify native file APIs are not GT dataset routes.

Validation checklist

  • Chat and embedding nodes succeed with expected aliases.
  • Knowledge features still work after credential rotation.
  • GT-only steps are documented for operators, not hidden behind failing provider assumptions.

Plain-text export

Dify runbook
OpenAI plus GT extensions ยท Workflow and builders
Recommended key preset: Chat plus embeddings framework client
Evidence: documented compatibility (vendor docs cross-check)

Add an OpenAI-API-compatible model provider in Dify pointed at GT API for chat and embeddings; implement GT upload and conversation routes as explicit HTTP workflow steps.

Official documentation:
- https://docs.dify.ai/guides/model-configuration/openai
- https://docs.dify.ai/guides/workflow/node/llm
- https://docs.dify.ai/guides/workflow/node/http-request

Configuration fields:
- OpenAI-API-compatible โ†’ API Base URL: https://<tenant-host>/api/tenant
- OpenAI-API-compatible โ†’ API Key: gtak_...
- LLM node โ†’ Model (published alias): published-agent-alias

GT route mapping:
- GET /v1/models (native): Dify provider test + manual `GET /v1/models` during provider setup
- POST /v1/chat/completions (native): App/workflow LLM node โ†’ `/v1/chat/completions` via OpenAI-compatible provider
- POST /v1/embeddings (native): Embedding model selection through same provider โ†’ `/v1/embeddings`
- POST /v1/audio/transcriptions (not_supported): Not exposed through Dify OpenAI-compatible provider by default
- POST /v1/audio/speech (not_supported): Not exposed through Dify OpenAI-compatible provider by default
- POST /v1/images/generations (not_supported): Requires image-capable published target and GT image scope if used
- POST /v1/conversations/files (gt_extension): Workflow HTTP Request multipart with GT conversation header
- POST /v1/datasets/{id}/files (gt_extension): Workflow HTTP Request to dataset files route
- GET /v1/files/{id} (gt_extension): Workflow HTTP GET poll on file id

Not supported in this product:
- Dify vendor-native OpenAI file and assistant APIs do not map to GT dataset or conversation upload semantics.

Prerequisites:
- Publish aliases for Dify apps and workflows.
- Grant `inference:chat` and `inference:embed` on key when knowledge/RAG uses GT embeddings.

Setup steps:
1. Dify console โ†’ Model Provider โ†’ OpenAI-API-compatible โ†’ set Base URL to tenant GT API.
2. Paste GT API key and save provider credentials.
3. Select a published alias in an app LLM node; run test completion.
4. Add HTTP Request node in workflows for GT conversation bootstrap or dataset uploads when required.

GT extensions and caveats:
- Call `POST /v1/conversations` from a workflow tool you control, not from default OpenAI provider shortcuts.
- Use `/v1/datasets/{id}/files` from HTTP nodes โ€” Dify native file APIs are not GT dataset routes.

Validation checklist:
- Chat and embedding nodes succeed with expected aliases.
- Knowledge features still work after credential rotation.
- GT-only steps are documented for operators, not hidden behind failing provider assumptions.