Type a CometAPI Chat Request in TypeScript

Last reviewed: 2026-07-16

Direct answer

For a conservative TypeScript request type, start with the fields the CometAPI chat completion reference shows as part of a basic chat request: a model string and a messages array with role/content objects. Keep optional controls narrow and documented, and leave provider-specific fields as an explicit extension type until your team verifies them against the linked reference.

type CometApiChatRole = "system" | "developer" | "user" | "assistant" | "tool";

type CometApiTextPart = {
  type: "text";
  text: string;
};

type CometApiImageUrlPart = {
  type: "image_url";
  image_url: {
    url: string;
    detail?: "low" | "high" | "auto";
  };
};

type CometApiChatContent = string | Array<CometApiTextPart | CometApiImageUrlPart>;

type CometApiChatMessage = {
  role: CometApiChatRole;
  content: CometApiChatContent;
  tool_call_id?: string;
};

type CometApiChatRequest<TExtra extends Record<string, unknown> = Record<string, never>> = {
  model: string;
  messages: CometApiChatMessage[];
  stream?: boolean;
  temperature?: number;
  max_tokens?: number;
  max_completion_tokens?: number;
  response_format?: unknown;
  tools?: unknown[];
} & TExtra;

Use this type as a fixture boundary, not as a promise that every model accepts every optional field. For production validation, pair it with Validate CometAPI Chat Completions for Production and keep source checks close to the request you actually send.

Who this is for

This guide is for TypeScript maintainers who need a request shape for CometAPI chat examples, contract fixtures, and client wrappers. It is intentionally conservative: it helps teams avoid hard-coding account-specific limits, prices, model availability, or provider-only behavior into shared tutorial code.

It is also useful when a tutorial repository has several examples in different languages and you want a common request fixture to compare them. The type gives reviewers a shared vocabulary for the request body without turning the TypeScript definition into a substitute for the current API reference. If your example moves beyond a simple chat request, such as a response-oriented workflow or a provider-specific feature, treat that as a new verification step instead of expanding this type casually.

Key takeaways

• Treat model as a string supplied by the caller after checking the current model source.
• Type messages as an ordered array, because the chat reference documents multi-message conversations and message roles.
• Keep multimodal content as a union so text-only examples stay simple while image input remains explicit.
• Add optional controls only when the current chat reference supports the contract area you are using.
• Do not assert pricing, rate limits, uptime, or model availability from this request type.
• Keep the request type separate from response parsing; response fields deserve their own fixture and storage review.

Request workflow

Setup assumptions: the maintainer has a CometAPI account, a valid API key stored outside source control as <API_KEY_PLACEHOLDER>, and a model identifier selected from the current CometAPI model source before the test begins. The local client is configured with the current CometAPI documentation rather than copied from an older tutorial.

Happy-path request plan: build a minimal CometApiChatRequest with a verified model string, one user message, and no optional controls. Serialize the object through the same client code path the tutorial will show. Send it with the documented chat completion endpoint pattern and record whether the response contains a top-level identifier, an object/type marker, at least one choice, and usage fields when present. Keep the prompt short and non-sensitive so a failed test can be discussed without exposing private data.

Error-path check: send one deliberately incomplete fixture with the messages field omitted in a non-production environment. Confirm that the client records an error object without logging the API key, full prompt text, or full response body. The goal is to prove that the wrapper handles a bad fixture predictably, not to document every possible error code.

Minimum assertions: request serialization matches the TypeScript type, the happy-path request returns a success status, the error-path request returns a handled failure, and logs redact credentials. If a model-specific option is added later, add a separate assertion that names the option, cites the source used to justify it, and records whether it was included in the fixture.

Pass/fail logging fields:

check_id: "chat-request-type-smoke-test"
checked_at: "YYYY-MM-DDTHH:MM:SSZ"
endpoint_family: "chat_completions"
model_source_checked: "yes|no"
request_fixture_name: "minimal-chat-request"
happy_path_result: "pass|fail"
error_path_result: "pass|fail"
redaction_result: "pass|fail"
notes: "placeholder only; no prompts, credentials, prices, limits, or full responses"

What not to assert: do not claim latency targets, rate-limit ceilings, account billing behavior, provider availability, or exact model-specific parameter support from this smoke test. Those belong in separate checks with direct source support. For related fixture hygiene, see Review CometAPI Request Bodies Before Tutorial Tests and Read CometAPI Text Responses Without Guessing the Shape .

Sources checked

• CometAPI documentation - accessed 2026-07-16; purpose: verify current CometAPI documentation navigation.
• CometAPI chat completions reference - accessed 2026-07-16; purpose: verify chat completion contract areas.
• CometAPI help center - accessed 2026-07-16; purpose: verify support and escalation documentation areas.
• CometAPI responses reference - accessed 2026-07-16; purpose: verify responses endpoint contract areas.

Contract details to verify

Failure modes

• Evidence gap: the maintainer 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 repair changes files or examples that are not connected to the observed TypeScript request problem. Keep the fix tied to the fixture and leave unrelated cleanup for a separate task.
• Environment mismatch: the local check uses different dependency versions, credentials, feature flags, or runtime settings than the hosted path. Record the mismatch before treating the result as proof.
• Unreviewed fallback: the example changes models, endpoints, permissions, or retry behavior to make a run pass without preserving the documented boundary. Treat access and provider failures as setup problems, not type problems.
• Weak handoff: the final note says the issue is fixed but omits the command, result, changed files, and remaining uncertainty. That makes the next maintainer repeat the investigation.

Reader next step

Copy the TypeScript type into a local fixture file, replace the model placeholder only after checking the current model source, and run one minimal chat request plus one redacted error-path check. If the request is for a real CometAPI integration, start from the current account and model pages instead of an old saved snippet: Start with CometAPI .

Before sharing the fixture with a team, add a short note beside it that names the source URLs checked, the date checked, the client package version, and the exact optional fields intentionally included. That note should be boring and specific. It should not include a prompt, a full response body, an API key, a price, a rate limit, or a promise that another model will behave the same way.

FAQ

Should the TypeScript type include a fixed model ID?

No. Keep model as a string and select the actual identifier from the current model source before running a request. A fixed identifier in a shared type makes old examples look authoritative after the model catalog changes.

Should every optional chat parameter be typed up front?

No. Add optional fields only when your example uses them and the current reference supports the contract area. Leave provider-specific additions in an extension type so the base fixture stays stable.

Can this type prove that a request will work for every model?

No. It only keeps your local fixture shape aligned with documented chat request areas. Model-specific behavior still needs a source check and a smoke test.

Where should failed request details go?

Record a sanitized pass/fail log with placeholder values only. Do not store credentials, full prompts, full responses, prices, limits, or model availability claims in the article fixture.

When should I use the Responses reference instead?

Use the Responses reference when the tutorial is centered on response-oriented text generation rather than a chat completion fixture. Do not stretch the chat request type to cover a different endpoint family without checking that endpoint directly.