How to Choose the Right CometAPI Model for Your Tutorial Code Samples

Last reviewed: 2026-06-10

Direct answer

When you write tutorial code samples that call CometAPI, the model identifier you pass in the request body is the most consequential decision you will make before publishing. Pick the wrong identifier and your readers get unhelpful errors. Pick one that works today but is undocumented and your sample breaks silently after a catalog update.

The safest practice is: look up the current model list from the CometAPI models reference, verify the identifier resolves at the chat completions or Responses endpoint in a short smoke test, and use only identifiers that appear in the official catalog at the time you write the sample. Exact model identifiers, availability status, and any associated constraints must be verified in the live docs linked below before you finalise any code sample.

For broader release checks, see Validate CometAPI Chat Completions for Production.

Who this is for

This guide is for developers who are:

• Writing tutorial articles, blog posts, or documentation that include CometAPI code samples.
• Building quick-start examples, workshop notebooks, or integration templates that others will copy and run.
• Maintaining existing samples and need to confirm the model identifiers in them are still valid.
• Onboarding to CometAPI and unsure which model to reference in a first working example.

If you are building a production integration rather than a tutorial, see How to Validate the CometAPI Model Catalog Before Integration for a more complete pre-production checklist.

Key takeaways

• Model identifiers come from the CometAPI model catalog. Verify the exact string at the models reference page before putting it in any sample.
• The chat completions endpoint and the Responses endpoint are both available; the right one depends on which interface your tutorial targets. Verify the current endpoint path, required fields, and response shape at the official docs before drafting request examples.
• Code samples should use clearly marked placeholder model identifiers (such as “model”: “”) when the exact identifier cannot be verified at write time, rather than embedding an identifier that may become stale.
• Smoke-test any sample that uses a real identifier before you publish: a single request that confirms the endpoint accepts the model identifier and returns a non-error response is sufficient gating.
• Exact pricing, rate limits, quota behaviour, and billing details are account-specific and should not be asserted in tutorial code or tutorial prose. Refer readers to the official documentation for those areas.

Notes on picking a model for sample code

Start from the catalog, not from memory

Model identifiers in CometAPI follow a naming convention described in the models reference. The catalog lists which identifiers are currently available, their capability category, and any relevant status notes. Before writing a sample, load the models reference page (linked in Sources checked below) and confirm the identifier string you intend to use is present.

Do not rely on identifiers you remember from a previous tutorial, an earlier project, or an unofficial list. Model catalogs change: identifiers can be added, versioned, or deprecated. A sample that uses a retired identifier fails immediately for your readers.

Understand the endpoint the sample will call

CometAPI exposes at least two text-generation endpoints: the chat completions path and the Responses path. Each has its own required request fields, response shape, and example payloads described in the official docs. Before choosing which endpoint to demonstrate in a sample:

1. Decide what interaction pattern your tutorial is teaching — conversational multi-turn, single-turn text generation, or something else.
2. Check the chat completions reference and the Responses reference (both linked below) for the current required request fields and the expected response structure.
3. Confirm the model identifier you selected is valid for the endpoint you chose. Not every model in the catalog may be available on every endpoint; verify this in the docs.

For a side-by-side comparison of when to use each endpoint, see Choose between CometAPI Chat Completions and Responses.

Use safe placeholder patterns for shareable samples

If you cannot verify a model identifier is current at the time of writing, or if the tutorial is intentionally endpoint-agnostic, use a clearly marked placeholder:

{
  "model": "<your-model-id>",
  "messages": [
    {"role": "user", "content": "Hello, world"}
  ]
}

This pattern signals to readers that they must supply a real identifier from the catalog. It is safer than embedding a specific identifier that may not be valid on their account or at their time of reading.

When you do embed a real identifier (for a tutorial that specifically demonstrates a named model), add a note near the code directing readers to verify the identifier is still current in the models reference before running the sample.

What not to assert in tutorial code samples

Keep the following out of tutorial request examples and surrounding prose, because they are account-specific, change frequently, or require live verification:

• Specific pricing per token or per request.
• Rate limit or quota values.
• Uptime or latency guarantees.
• Model availability on specific dates.
• Billing field names or values.

For any of these, link readers to the appropriate official documentation page rather than asserting a value.

Smoke-test workflow

Setup assumptions

• You have a CometAPI API key available in your local environment (never hard-code keys in tutorial samples).
• You have chosen an endpoint path (chat completions or Responses) and verified it in the docs.
• You have an identifier string from the current model catalog.

Happy-path request plan

Send a minimal single-message request to the endpoint you are documenting. The body should include only the fields the docs list as required: the model identifier, the input message or messages array, and any other required fields. Keep the prompt short and deterministic (for example, ask for a one-word reply) so the response is easy to inspect.

Expected outcome: the endpoint returns a 200-level HTTP status and a response body whose shape matches the documented response schema (an object containing a choices or output array, depending on the endpoint).

Error-path check

Repeat the same request with a deliberately invalid model identifier (for example, “model”: “does-not-exist-test”). The endpoint should return a 4xx error. Confirm the error response structure in the docs so you can show readers what a model-not-found or invalid-request error looks like.

Minimum assertions

• HTTP status is 200 for the valid request.
• HTTP status is 4xx for the invalid-identifier request.
• The response body for the valid request contains the documented output field(s).
• No credentials appear in the response body.

What the smoke test must not assert

• Specific response content (the model output is non-deterministic).
• Exact latency values.
• Token counts, cost, or billing fields.
• That a specific model identifier will remain valid in the future.

Sample log record template

Record the following after each smoke-test run. Use placeholder values only; do not log real API keys, full prompts, or complete response bodies.

smoke_test_run: date: YYYY-MM-DD endpoint: model_id_tested: http_status_happy_path: http_status_error_path: response_shape_matches_docs: true|false notes: tester:

Failure modes

• Evidence gap: the agent cannot inspect the failing log, source page, pull request, or local command output. The safe action is to stop and record the missing evidence instead of guessing.
• Scope drift: the agent edits files that are not connected to the observed failure. Keep the repair tied to the failing signal and leave unrelated cleanup for a separate task.
• Environment mismatch: the local check uses different versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
• Unreviewed fallback: the agent changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the review boundary. Treat access and provider failures as operational blockers, not topic failures.
• Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next operator repeat the investigation.

Sources checked

• CometAPI documentation - accessed 2026-06-10; purpose: verify current CometAPI documentation navigation.
• CometAPI models overview - accessed 2026-06-10; purpose: verify model catalog discovery guidance.
• CometAPI chat completions reference - accessed 2026-06-10; purpose: verify chat completion contract areas.
• CometAPI responses reference - accessed 2026-06-10; purpose: verify responses endpoint contract areas.
• CometAPI help center - accessed 2026-06-10; purpose: verify support and escalation documentation areas.

Contract details to verify

Reader next step

Compare the workflow against Start with CometAPI.

Use How to Smoke-test the CometAPI Chat Completion Contract as the next comparison point. Keep Review a CometAPI chat completions contract nearby for setup and permission checks.

FAQ

Can I use any model identifier I find in a forum post or third-party list? No. Only identifiers listed in the official CometAPI model catalog at the time you publish your sample are safe to use. Third-party lists may be stale, incomplete, or based on private access. Always verify at the models reference page linked in Sources checked.

Should I hard-code the API key in my tutorial sample? Never. Tutorial samples should read the key from an environment variable (for example, os.environ[“COMET_API_KEY”] in Python or process.env.COMET_API_KEY in Node). This is both a security requirement and a good habit to model for your readers.

What if the model identifier I want to use is in the catalog but the endpoint returns an error? Record the error response body and HTTP status, then check the model-endpoint compatibility notes in the models reference. Some models may be listed in the catalog but restricted to specific endpoints or account tiers. If the issue persists, use the help center (linked in Sources checked) to open a support request.

Can I assert in my tutorial that a given model will always be available? No. Model availability is subject to change. Use present-tense wording (“this model is currently available”) and direct readers to re-verify the catalog when they run your sample. Better still, use the placeholder pattern and let readers pick from the current catalog.

Which endpoint should I use for a first tutorial sample? Check the chat completions reference and the Responses reference (both in Sources checked) to understand which interaction pattern each endpoint supports. Pick the one that best matches what your tutorial is teaching. If you are building a simple question-and-answer example, the chat completions endpoint is a common starting point, but verify the current docs to confirm it matches your use case.

Where do I find help if my sample stops working? Start with the official documentation pages linked in Sources checked. If the issue is an account-level or billing question, use the CometAPI help center. If you believe the docs or catalog contain an error, report it through the support path described in the help center.

Start with CometAPI