docs: add AI Credits guide

docs.json

@@ -225,7 +225,13 @@
                     "expanded": false,
                     "pages": [
                       "en/cloud/use-dify/workspace/plugins",
-                      "en/cloud/use-dify/workspace/model-providers",
+                      {
+                        "group": "Model Providers",
+                        "root": "en/cloud/use-dify/workspace/model-providers",
+                        "pages": [
+                          "en/cloud/use-dify/workspace/ai-credits"
+                        ]
+                      },
                       "en/cloud/use-dify/workspace/tools",
                       {
                         "group": "Custom Endpoint",
@@ -5128,11 +5134,11 @@
     },
     {
       "source": "/en/guides/model-configuration/load-balancing",
-      "destination": "/en/cloud/use-dify/workspace/model-providers#configure-model-load-balancing"
+      "destination": "/en/cloud/use-dify/workspace/model-providers#spread-requests-across-api-keys-with-load-balancing"
     },
     {
       "source": "/guides/model-configuration/load-balancing",
-      "destination": "/en/cloud/use-dify/workspace/model-providers#configure-model-load-balancing"
+      "destination": "/en/cloud/use-dify/workspace/model-providers#spread-requests-across-api-keys-with-load-balancing"
     },
     {
       "source": "/zh-hans/guides/model-configuration/load-balancing",

en/cloud/use-dify/workspace/ai-credits.mdx

@@ -0,0 +1,98 @@
+---
+title: AI Credits
+description: Learn how AI credits work in your workspace, from model costs to usage priority
+---
+
+Each Dify Cloud plan includes a set number of AI credits for using supported models hosted by Dify. They give you immediate access to models from different providers, so you can start building and testing apps without first adding your own API keys.
+
+App runs that use AI credits draw from the workspace's shared balance, including runs from the editor, published web apps, the Service API, and triggers.
+
+## Understand AI Credit Usage
+
+Your workspace may use AI credits whenever a supported model runs. Common cases include:
+
+- **Running an app with an LLM**, whether configured directly in a Chatbot, Text Generator, or Agent app or through an LLM, Question Classifier, Parameter Extractor, or Agent node in a Workflow or Chatflow.
+- **Using AI-assisted generation in the app editor** to create or revise prompts, code, structured output configurations, or Workflow and Chatflow drafts.
+- **Indexing or searching a knowledge base**, which may run an embedding model for indexing or vector search, an LLM to generate Q&A chunks from source documents, or a rerank model when reranking is enabled.
+- **Transcribing voice input or generating audio output in an app** with a speech-to-text or text-to-speech model.
+
+Each model has a fixed credit cost that applies every time it runs, regardless of input or output length. Iterations, Loops, Agent reasoning, and knowledge base indexing may run a model more than once.
+
+For example, a Workflow uses a 5-credit LLM in an Iteration to analyze three customer reviews, then uses the same LLM to summarize the findings. The four runs use 20 AI credits in total.
+
+## Compare Model Costs
+
+The following costs apply each time a model runs:
+
+<AccordionGroup>
+  <Accordion title="OpenAI">
+
+    - **25 credits**: `gpt-5.6-sol`, `gpt-5.5`.
+    - **20 credits**: `gpt-4`.
+    - **15 credits**: `gpt-5.6-terra`, `gpt-5.4`.
+    - **10 credits**: `gpt-5.2`, `gpt-4o`, `gpt-4o-transcribe-diarize`, `gpt-4o-transcribe`, `whisper-1`, `gpt-4o-mini-tts-2025-12-15`, `tts-1-hd`, `tts-1`.
+    - **5 credits**: `gpt-5.6-luna`, `gpt-5.4-mini`, `gpt-5`, `gpt-5.1`, `gpt-4.1`, `o3-mini`, `o4-mini`, `gpt-4o-mini-transcribe-2025-12-15`, `gpt-4o-mini-transcribe`, `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`.
+    - **1 credit**: `gpt-5-mini`, `gpt-4.1-mini`, `gpt-4o-mini`, `gpt-3.5-turbo`.
+
+  </Accordion>
+  <Accordion title="Anthropic">
+
+    - **20 credits**: `Claude Opus 4.7`, `Claude Opus 4.6`, `Claude Opus 4.5`.
+    - **10 credits**: `Claude Sonnet 4.6`, `Claude Sonnet 4.5`.
+    - **5 credits**: `Claude Haiku 4.5`.
+
+  </Accordion>
+  <Accordion title="Gemini">
+
+    - **10 credits**: `Gemini 3.5 Flash`, `Gemini 3.1 Pro-Preview`.
+    - **5 credits**: `gemini-3.7-flash`, `gemini-embedding-001`, `gemini-embedding-2`.
+    - **3 credits**: `Gemini 3 Flash-Preview`.
+    - **1 credit**: `Gemini 3.5 Flash-Lite`, `Gemini 3.1 Flash-Lite-Preview`, `Gemini 3.1 Flash-Lite`, `Gemini 2.5 Flash`, `Gemini 2.0 Flash`, `Gemini 2.0 Flash-Lite`.
+
+  </Accordion>
+  <Accordion title="xAI">
+
+    - **20 credits**: `grok-4.5`, `grok-4.6`.
+    - **10 credits**: `grok-4.3`.
+
+  </Accordion>
+  <Accordion title="Tongyi">
+
+    - **20 credits**: `qwen3-tts-flash`.
+    - **10 credits**: `qwen3.7-max`, `qwen3.7-max-preview`, `qwen3.6-max-preview`, `qwen3-max`, `qwen3-max-preview`, `qwen-max`, `qwen3.6-plus`, `qwen-plus`, `qwen-plus-latest`, `qwen3.5-omni-plus`, `qvq-max`.
+    - **5 credits**: `qwen3.5-plus`, `qwen3.6-flash`, `qwen-flash`, `qwq-plus`, `qwen3.5-omni-flash`, `qwen3-vl-plus`, `qwen-vl-max`, `text-embedding-v3`, `text-embedding-v4`.
+    - **1 credit**: `qwen3.7-plus`, `qwen3.5-flash`, `qwen-turbo`, `qwen-long-latest`, `qwen-long-2025-01-25`, `qwen3-vl-flash`, `qwen-vl-plus`, `qwen3-rerank`.
+
+  </Accordion>
+</AccordionGroup>
+
+<Note>
+Models not listed above are not available through AI credits. [Add your own API keys](/en/cloud/use-dify/workspace/model-providers#use-your-own-api-key) to use them.
+</Note>
+
+## Check Your AI Credits
+
+Check your remaining AI credits below your workspace name. Click the balance to open **Integrations** > **Model Provider** for usage details.
+
+The number of included AI credits depends on your plan:
+
+| Plan | Included AI Credits | Renewal |
+|:-----|:--------------------|:--------|
+| Sandbox | 200 | One-time allocation |
+| Professional | 5,000 | Monthly |
+| Team | 10,000 | Monthly |
+
+<Note>
+After upgrading to Professional or Team, your new plan's AI credits are used before any remaining Sandbox credits. The two balances cannot be combined for one model run.
+</Note>
+
+## Set Usage Priority
+
+For a provider that supports AI credits, the first API key you add is automatically used before AI credits. To change the order, go to **Integrations** > **Model Provider**, click **Configure** on the provider card, and set **Usage Priority**:
+
+- **AI credits first**: Requests use AI credits until they run out, then switch to the selected API key. If the remaining balance cannot cover the model's full cost, change the priority to **API Key**.
+- **API key first**: Requests use the selected API key. If a request cannot be sent with that key, it uses available AI credits.
+
+<Note>
+If a request has already been sent with your API key but fails, it is not retried with AI credits. Fix the API key or provider issue, or change the priority to **AI credits** before retrying.
+</Note>

en/cloud/use-dify/workspace/model-providers.mdx

@@ -1,43 +1,35 @@
 ---
 title: Model Providers
-description: Use models with your AI credits, or connect your own provider accounts and keys
+description: Use models with your AI credits, or connect your own provider accounts and API keys
 ---
 
-Every AI app you build runs on a model. Dify Cloud comes with popular models, and lets you connect your own provider accounts when you need more. 
+Models power many of the apps and features you build in Dify. Dify Cloud provides two ways to access them: use supported models with the AI credits included in your plan, or add your own API key to connect a provider account.
 
-Models are shared across the workspace, so your whole team works with the same ones.
+Models available through either option can be used across the workspace.
 
-<Warning>
-Only the workspace owner and admins can manage providers. Any key you add works across the whole workspace and bills to your own account with that provider.
-</Warning>
+## Use AI Credits
 
-## Use Models with Your AI Credits
+With AI credits, you can use supported models from different providers without adding API keys. Install one of these providers from **Integrations** > **Model Provider** (or the [Marketplace](https://marketplace.dify.ai/)), and its models are ready to use.
 
-Dify Cloud gives you AI credits to use models from a set of popular providers, so you don't need your own API key to start. 
+See [AI Credits](/en/cloud/use-dify/workspace/ai-credits) for credit costs and usage rules.
 
-Install one of these providers from **Integrations** > **Model Provider** (or the [Marketplace](https://marketplace.dify.ai/)), and its models are ready to use. Each AI response consumes your AI credits.
+## Use Your Own API Key
 
-An AI response is a single model call (one input and one output), and it counts as one response no matter how many tokens it uses. The number of credits a response costs depends on the model, with larger models costing more than smaller ones. 
+Add your own API key to access models through your provider account.
 
-See the [Dify pricing page](https://dify.ai/pricing) for which providers AI credits support and how many credits each model costs.
+<Note>
+Only the workspace owner and admins can add or manage provider API keys.
+</Note>
 
-## Use Your Own Account with a Supported Provider
+1. Go to **Integrations** > **Model Provider**.
 
-Add your own API key to a supported provider when you want higher rate limits or billing through your own provider account.
+2. Find the provider. If it is not installed, select it under **Install model providers** or find it in the [Marketplace](https://marketplace.dify.ai/).
 
-1. In **Integrations** > **Model Provider**, install the provider if it isn't already.
+3. Click **Add API Key**, then enter your API key and any other required details.
 
-2. Click **Setup** on its card, then enter your API key and any other required details. Dify checks the key before making the provider available.
+If the provider supports AI credits, both options remain available. Set [Usage Priority](/en/cloud/use-dify/workspace/ai-credits#set-usage-priority) to choose which one is used first.
 
-Your key and AI credits can coexist. Set **Usage Priority** on the provider card to control which one Dify draws from first and falls back to the other, so a key you add can simply take over once your credits run out.
-
-## Connect a Provider AI Credits Don't Support
-
-To use a provider that AI credits don't support, install it first and run it on your own account. AI credits don't apply to these providers.
-
-1. In **Integrations** > **Model Provider**, browse **Install model providers**, or open the [Marketplace](https://marketplace.dify.ai/) for the full list.
-
-2. Install the provider, click **Setup**, and enter your API key along with any other required details.
+Requests made with your API key go through your provider account and do not deduct AI credits. For providers that do not support AI credits, an API key is the only option.
 
 ## Add a Custom Model
 
@@ -46,18 +38,28 @@ A provider's models are ready as soon as you connect it, so you only add one by
 Click **Add Model** on the provider's card, then give the model a name and its credentials. Providers that serve only a fixed set of models don't offer this option.
 
 <Info>
-If the model you add matches the name and type of an existing one, Dify attaches the new key to that model instead of creating a duplicate.
+If the model you add matches the name and type of an existing one, Dify attaches the new API key to that model instead of creating a duplicate.
 </Info>
 
-## Manage Your Keys
+## Choose the Models Apps Use by Default
+
+Apps and nodes that don't pick a model fall back to your workspace defaults. Click **Default Models** at the top-right corner to set one for each job:
+
+- **System Reasoning Model**: the default for general LLM tasks.
+- **Embedding Model**: indexes and retrieves knowledge base content.
+- **Rerank Model**: reorders retrieval results by relevance.
+- **Speech-to-Text Model**: turns audio into text.
+- **Text-to-Speech Model**: turns text into audio.
 
-Add more than one key to a provider when you want to keep development and production apart or spread usage across several accounts.
+## Manage API Keys
 
-- For a provider's own models, click **Configure** on its card to manage the keys they share.
+Add more than one API key to a provider when you need to switch between provider accounts or configure load balancing for a model.
+
+- For the models listed on a provider card, click **Configure** on the card to manage the API keys they share.
   <Frame>
   ![Manage Credentials for a Provider's Models](/images/use-dify/workspace/predefined-model-credential.png)
   </Frame>
-- For a custom model you added, click **Configure** on that model to manage its own keys.
+- For a custom model you added, click **Configure** on that model to manage its own API keys.
     <Columns cols={2}>
       <Frame>
       ![Custom Model Configuration](/images/use-dify/workspace/custom-model-config.png)
@@ -68,51 +70,41 @@ Add more than one key to a provider when you want to keep development and produc
     </Columns>
 
     <Warning>
-    A custom model relies on its own keys. Deleting its only key removes the model too.
+    A custom model relies on its own API keys. Deleting its only API key removes the model too.
     </Warning>
 
-    To view every custom model's keys in one place, click **Manage Credentials** on the provider card.
+    To view every custom model's API keys in one place, click **Manage Credentials** on the provider card.
 
     <Frame>
       ![Manage Credentials for All Custom Models](/images/use-dify/workspace/custom-model-credential-list.png)
     </Frame>
 
-    Keys stay here even after the custom model is removed, so you can re-add the model later without re-entering its keys.
+    API keys stay here even after the custom model is removed, so you can re-add the model later without re-entering them.
 
     <Frame>
       ![Re-add a Removed Model](/images/use-dify/workspace/removed-custom-model-re-add.png)
     </Frame>
 
-## Choose the Models Apps Use by Default
-
-Apps and nodes that don't pick a model fall back to your workspace defaults. Click **Default Models** at the top-right corner to set one for each job:
-
-- **System Reasoning Model**: the default for general LLM tasks.
-- **Embedding Model**: indexes and retrieves knowledge base content.
-- **Rerank Model**: reorders retrieval results by relevance.
-- **Speech-to-Text Model**: turns audio into text.
-- **Text-to-Speech Model**: turns text into audio.
-
-## Spread Requests Across Keys with Load Balancing <Badge color="blue">Professional</Badge> <Badge color="blue">Team</Badge>
+## Spread Requests Across API Keys with Load Balancing <Badge color="blue">Professional</Badge> <Badge color="blue">Team</Badge>
 
-When one key handles many requests at once, it can hit the provider's rate limit and start failing. 
+When one API key handles many requests at once, it can hit the provider's rate limit and start failing.
 
-Use load balancing to spread requests across several keys for the same model, so no single key becomes the bottleneck. Dify rotates through the keys in turn and rests any that hits its limit for a minute before trying it again.
+Use load balancing to spread requests across several API keys for the same model, so no single API key becomes the bottleneck. Dify rotates through the API keys in turn and rests any that hits its limit for a minute before trying it again.
 
-1. Find the model in the list, click **Configure**, and select **Load Balancing**.
+1. Find the model in the list, click **Configure**, and select **Load balancing**.
 
-2. Click **Add credential** to add keys to the pool.
+2. Click **Add credential** to add API keys to the pool.
 
     <Tip>
-    Add a higher-quota or faster key more than once to send more of the traffic its way.
+    Add a higher-quota or faster API key more than once to send more of the traffic its way.
     </Tip>
 
     <Frame>
     ![Add Credentials for Load Balancing](/images/use-dify/workspace/add-load-balancing-credential.png)
     </Frame>
 
-3. Turn on at least two keys, then click **Save**. A model using load balancing shows a marker in the list.
+3. Turn on at least two API keys, then click **Save**. A model using load balancing shows a marker in the list.
 
 <Info>
-Switch back to a single key anytime; your load balancing setup is kept for later use.
-</Info>
+Switch back to a single API key anytime; your load balancing setup is kept for later use.
+</Info>

tools/translate/termbase_i18n.md

@@ -28,6 +28,8 @@
 |:--------|:--------|:---------|
 | model | 模型 | モデル |
 | model provider | 模型供应商 | モデルプロバイダー |
+| AI credits | AI 消息额度 | AI クレジット |
+| API key | API Key | API キー |
 | LLM (large language model) | 大语言模型 | 大規模言語モデル |
 | chat model | 对话模型 | チャットモデル |
 | completion model | 文本续写模型 | 補完モデル |
@@ -37,8 +39,8 @@
 | rerank model | 重排序模型 | リランクモデル |
 | reasoning model | 推理模型 | 推論モデル |
 | moderation model | 内容审核模型 | モデレーションモデル |
-| TTS model | 文字转语音模型 | TTSモデル |
-| Speech2Text model | 语音转文字模型 | 音声認識モデル |
+| speech-to-text model | 语音转文字模型 | 音声認識モデル |
+| text-to-speech model | 文字转语音模型 | TTSモデル |
 | token | token | token |
 | API token | API 令牌 | APIトークン |
 | prompt | 提示词 | プロンプト |
@@ -218,7 +220,7 @@
 | Rerank Model | Rerank 模型 | Rerank モデル |
 | Speech-to-Text Model | 语音转文本模型 | 音声-to-テキストモデル |
 | Text-to-Speech Model | 文本转语音模型 | テキスト-to-音声モデル |
-| Load Balancing | 负载均衡 | 負荷分散 |
+| Load balancing | 负载均衡 | 負荷分散 |
 | AI credits | AI 消息额度 | AI クレジット |
 | Usage Priority | 使用优先级 | 使用優先度 |
 | API Key | API Key | API キー |