Dify can place a model gateway behind a chatbot, workflow, or agent. A reliable setup has three matching pieces: the provider plugin, an exact model identifier, and an endpoint that supports the chosen capability. This guide uses the official CometAPI provider path, checks the public catalog before configuration, and finishes with a deliberately small chatbot test.

Last reviewed: 2026-08-26

Direct answer

You need a Dify account, cloud or self-hosted, and an active CometAPI API key. Store the key in the account’s approved secret store. If a key appears in a screenshot, fixture, or support note, replace it with [REDACTED]; do not print it or place it in a URL.

Begin with the public catalog. CometAPI’s model catalog reference documents a GET operation at /api/models that does not require an Authorization header. The response includes success and data; a record may include an exact id, provider, model type, feature tags, endpoint hints, and public pricing metadata. Copy the record’s id exactly. A display name or alias from an old configuration is not a substitute.

Use a query-free discovery command and inspect only metadata:

curl -sS "$COMETAPI_MODEL_CATALOG" |
  jq '.data[] | {id, provider, model_type, features, endpoints}'

Set COMETAPI_MODEL_CATALOG to the public catalog endpoint documented in the linked reference. Select a record whose model type, features, and endpoint hints fit an LLM chatbot. If the catalog reports an unsuccessful result, resolve discovery before editing Dify.

Now follow the recommended sequence in CometAPI’s Dify integration guide :

  1. In Dify, open Plugins, choose Install Plugin, select Marketplace, search for cometapi, and install the provider.
  2. Open Settings, choose Model Provider, select CometAPI, and open its settings.
  3. Paste the active key into the provider form and save it. Keep it out of prompts, workflow variables, source files, and published output.
  4. Choose Add model, enter the exact catalog id, and save the model entry.
  5. Create a small chatbot, select that model, and send: ‘Reply with exactly OK.’

A rendered answer is the happy-path proof that Dify reached the provider, resolved the model, and completed a chat request. Keep the first prompt short and deterministic. Once it succeeds, change one thing at a time, such as adding a single workflow node, and rerun the same prompt.

If the Marketplace plugin does not cover the model you need, use the documented fallback: Settings → Model Provider → OpenAI-API-compatible → Add Model. Set model type to LLM, enter the exact CometAPI model ID as the model name, provide the key, and use the CometAPI base URL including /v1. Save and repeat the same chatbot test. This separates provider selection from prompt or workflow behavior.

Who this is for

This walkthrough is for Dify builders, product engineers, and developers who want CometAPI models in a chatbot, workflow, or agent without writing a custom adapter. It suits a first integration, a demo workspace, or a troubleshooting session where a model appears in a selector but fails when a run starts.

You should be able to open Dify settings and create or use a CometAPI key. The article does not replace a review of workspace permissions, published-app access, data retention, or the kinds of user content your application may send. The plugin handles provider configuration; your team still owns application policy and secret hygiene.

Key takeaways

  • Fetch the public /api/models catalog and copy an exact id before adding a model.
  • Use Marketplace plugin → CometAPI provider settings → Add model → tiny chatbot test.
  • Check provider, model type, features, and endpoint hints together; a plausible name is not enough.
  • A saved form or visible dropdown is a configuration milestone, not a successful request.
  • Keep a deterministic prompt and change one variable at a time while diagnosing.
  • Use the OpenAI-compatible provider when the plugin path does not cover the model.
  • Log outcomes and identifiers, never keys, authorization values, or full prompts.

For a model-record preflight, see the CometAPI model-catalog validation checklist . For a separate chat client after this baseline works, see the Open WebUI multi-model setup guide .

Sources checked

The setup sequence is documented in CometAPI’s Dify integration guide . The page lists cloud and self-hosted prerequisites, recommends the Marketplace plugin, gives the Model Provider path, requires an exact model ID, uses a chatbot or workflow message as a test, and documents the OpenAI-compatible fallback with its /v1 requirement.

The public provider listing is independently visible in the CometAPI entry on Dify Marketplace . It identifies CometAPI as a model provider and describes a configuration flow in which the provider is enabled in Dify’s Model Provider settings. The listing is useful availability evidence; it is not a replacement for checking the live model ID.

Dify’s plugin documentation defines plugins as modular components that connect external APIs, process data, and package model capabilities for Dify applications. CometAPI’s model catalog documentation defines the public catalog operation and the metadata fields used for model and endpoint selection. These four pages support the installation path, the plugin boundary, and the catalog-first check.

Contract details to verify

Installation surface. The recommended route is Plugins → Install Plugin → Marketplace. Search for cometapi in that surface and confirm installation finishes before opening provider settings. If your deployment has no Marketplace access, use the documented OpenAI-compatible provider rather than guessing a package name.

Credential boundary. Put the active key only in the CometAPI provider form. A successful save means Dify accepted the configuration; it does not prove a model request will run. Keep keys out of prompts, workflow outputs, source control, screenshots, and logs. If an operator needs to share a configuration record, use [REDACTED].

Model identity. Enter the catalog record’s id, preserving case, punctuation, and suffixes. Check provider, model_type, features, and endpoints as well. A valid image or video record can still be wrong for an LLM chatbot. Re-fetch the catalog when a model is renamed, retired, or missing from a later test.

Connection proof. Use a new or minimal chatbot, select the model, and send the same short prompt each time. A response is stronger evidence than a model appearing in a dropdown. Retain a request ID or status if Dify exposes one; otherwise retain the UI result and a local timestamp.

Fallback endpoint. The fallback form uses model type LLM, the exact model name, the CometAPI key, and the documented base URL including /v1. Keep that endpoint query-free. Never append a credential parameter to it.

A sanitized operator record can look like this:

event: dify_cometapi_connection_test
provider: CometAPI
model_id: MODEL_ID_FROM_CATALOG
operation: chatbot_test
outcome: success
http_status: 200
request_id: REQUEST_ID_IF_RETURNED
credential_logged: false
prompt_logged: false

These placeholders are intentionally non-secret. If no request ID is available, record a local timestamp and the visible outcome. Do not replace either false flag with a key or unredacted content.

Failure modes

The provider is missing. Confirm that you are in Dify’s Plugins Marketplace, not only the model selector, and search for cometapi. Check the Dify Marketplace listing . If Marketplace installation is unavailable, use the OpenAI-compatible route from the integration guide.

The key is rejected. Re-enter the active key in Settings → Model Provider → CometAPI, save, and repeat the short chatbot test. Check key validity and available balance before changing the model. Do not test a key by printing it, putting it in a URL, or pasting it into a prompt.

The model ID is rejected. Fetch the catalog again and compare Dify’s value with the record’s id character for character. Replace a display label or stale alias with the listed identifier, then confirm that model type and feature tags fit the chatbot.

The fallback base URL fails. Confirm that the OpenAI-compatible value includes /v1. A host-only value or a different endpoint family can fail even when the key is valid. Save the corrected form and run the unchanged deterministic prompt.

The model appears but the chatbot fails. Inspect endpoint hints and feature tags, and verify that the Dify node is an LLM chat use case. A dropdown entry is not network proof. If the catalog call itself is unsuccessful, treat discovery as the first failure instead of repeatedly editing provider settings.

The response is slow or incomplete. Remove optional workflow nodes and keep the prompt short. If the minimal chatbot works, add one feature at a time and retain the last successful model ID. This isolates provider onboarding from later workflow behavior.

A configuration value leaks. Stop sharing the diagnostic, rotate the affected credential through the account’s normal process, and replace the retained value with [REDACTED]. Future records should contain only provider, model ID, operation, status, request ID when available, and the two false logging flags.

FAQ

Do I need a custom SDK or adapter?

No custom adapter is required for the Marketplace route described by CometAPI. Install the provider, configure it in Dify’s Model Provider settings, add a catalog-verified model ID, and test a chatbot or workflow. Use the OpenAI-compatible provider when the plugin route does not cover the model.

How do I choose a current model ID?

Use the public catalog immediately before setup. Copy its id and inspect provider, model type, features, and endpoint hints. Do not infer an identifier from a screenshot, display label, or old configuration.

Does the catalog call require my key?

No. The catalog reference documents a public GET operation without an Authorization header. That discovery call is separate from the authenticated model request made after provider configuration. Keep the key only in Dify’s provider settings.

Can I use Claude, Grok, or Gemini models?

The integration guide names those families as examples for the OpenAI-compatible fallback. Confirm the exact listed ID and endpoint compatibility, configure the fallback as an LLM with the documented base URL, and test one model at a time.

What should I record for support?

Record provider, exact model ID, operation, local timestamp, visible outcome or HTTP status, request ID when available, and a broad error class such as key, balance, model, or base URL. Set credential and prompt logging to false. Never include a key, a full authorization value, or unredacted user content.

Reader next step

Run the catalog command and save only one model’s exact id, provider, model type, and capability notes. Install the CometAPI plugin in Dify, configure the provider, add that ID, and send ‘Reply with exactly OK.’ in a new chatbot. If it succeeds, record the sanitized fields and make one small workflow change before testing again. If it fails, classify the result as discovery, key or balance, model identity, endpoint, or workflow behavior, then follow the matching failure mode above. You will have a known-good baseline before publishing a larger Dify application.