Last reviewed: 2026-08-08

Direct answer

A CometAPI vision API Node.js client needs four pieces: an OpenAI Node.js SDK client configured for CometAPI, a model verified to accept image input through the Responses route, an input array containing text and image items, and explicit validation of the returned status and text. The refetched CometAPI Responses reference documents POST /v1/responses, multimodal input arrays, and the output_text convenience field. The CometAPI OpenAI SDK guide documents the Node.js client configuration and the required CometAPI base URL.

Do not treat visual capability and route compatibility as the same check. A model can understand images while a particular provider route exposes a different contract. CometAPI’s Responses documentation explicitly warns that providers can support different parameters and return different fields. Verify the current model and route together before making the model ID a production default.

Install the SDK:

npm install openai

Add the following function to the server-side module that owns visual requests. It receives an already configured SDK client from your application’s authentication boundary, so the visual workflow never handles or logs credential material. Construct that client separately using the refetched SDK guide.

export async function askImageQuestion({
  client,
  model,
  imageUrl,
  question,
  log = console.error,
}) {
  const startedAt = Date.now();
  let stage = 'preflight';
  let responseId = null;
  let responseStatus = null;

  try {
    if (!client || !model) {
      throw new Error('Configured client and model are required.');
    }
    if (!imageUrl || !question?.trim()) {
      throw new Error('Image input and question are required.');
    }

    const parsedImage = new URL(imageUrl);
    if (parsedImage.protocol !== 'https:') {
      throw new Error('The image URL must use HTTPS.');
    }

    stage = 'request';
    const response = await client.responses.create({
      model,
      input: [
        {
          role: 'user',
          content: [
            { type: 'input_text', text: question.trim() },
            { type: 'input_image', image_url: imageUrl },
          ],
        },
      ],
    });

    responseId = response.id ?? null;
    responseStatus = response.status ?? null;
    stage = 'response_validation';

    if (responseStatus && responseStatus !== 'completed') {
      throw new Error('The response did not complete.');
    }

    const answer = response.output_text?.trim();
    if (!answer) {
      throw new Error('The response contained no output text.');
    }

    stage = 'complete';
    log(JSON.stringify({
      event: 'cometapi_visual_qa',
      outcome: 'success',
      stage,
      model,
      response_id: responseId,
      response_status: responseStatus,
      image_host: parsedImage.hostname,
      question_chars: question.length,
      answer_chars: answer.length,
      duration_ms: Date.now() - startedAt,
    }));

    return {
      ok: true,
      answer,
      responseId,
      responseStatus,
    };
  } catch (error) {
    const status = Number(error?.status);
    const knownStatus = Number.isInteger(status) ? status : null;

    log(JSON.stringify({
      event: 'cometapi_visual_qa',
      outcome: 'error',
      failure_stage: stage,
      model: model ?? null,
      http_status: knownStatus,
      request_id: error?.request_id ?? null,
      response_id: responseId,
      response_status: responseStatus,
      error_name: error?.name ?? 'Error',
      retry_candidate:
        knownStatus === 429 || (knownStatus !== null && knownStatus >= 500),
      duration_ms: Date.now() - startedAt,
    }));

    return {
      ok: false,
      httpStatus: knownStatus,
      responseId,
      responseStatus,
    };
  }
}

The function returns the answer to its caller and sends only sanitized metadata to the injected logger. A command-line boundary may explicitly render the returned answer for a human, while a server handler can choose a product-specific response. The operational record deliberately excludes authentication material, the full image URL, question, answer, and raw error message. It records the image host, character counts, model ID, response identifiers when available, status, stage, and duration. Because the response ID and status are copied immediately after the request returns, the error record retains them even when status validation or output extraction fails.

Use this happy-path and error-path workflow:

  1. Configure the documented CometAPI base URL and authentication inside a separate server-side boundary. Pass the resulting SDK client into askImageQuestion.
  2. Choose a model ID that you have verified against the current model catalog and the Responses route.
  3. Select a controlled, non-sensitive HTTPS image with an obvious expected answer. Use a narrow question such as asking for the dominant object or visible text.
  4. Run the function once. A happy path returns ok: true, a nonempty answer, a success event, and a completed status when the provider returns one. The caller, not the helper, decides whether to print or render the answer.
  5. Compare the answer with the known fixture. A syntactically successful response is not enough if it ignored the image.
  6. Exercise the error path with a missing image argument and then with a deliberately invalid model selection. Confirm that the function returns ok: false and that logs contain no question, image path, answer, authentication material, or raw error body.
  7. Exercise a non-completed response or empty output in a test double. Confirm that response_id and response_status remain in the error event when the service supplied them.
  8. Treat 429 and server-side statuses as retry candidates subject to your retry budget. Do not automatically retry configuration, authentication, model-selection, or response-contract failures.

Before fixing the client around one route, review the endpoint selection guide .

Who this is for

This guide is for Node.js developers building a server-side visual question-answering feature through CometAPI. It assumes you can install an npm package, provide a configured SDK client through an existing server-side boundary, and operate a small smoke test before connecting the request to a web route or job worker.

It is especially useful when your application needs to describe a photograph, inspect a screenshot, read visible text, or ask a focused question about an image. The refetched CometAPI model page and upstream Qwen repository describe visual perception, OCR, grounding, and visual question-answering capabilities, but the implementation still needs a separate route-compatibility test.

This is not an image-generation tutorial. The request sends an existing image as model input and expects text as the application result. It also does not assume that every multimodal model accepts every optional Responses parameter.

Key takeaways

  • CometAPI documents POST /v1/responses with an input value that can contain text, image, or file items.
  • The Node.js SDK must target the CometAPI base URL and use a current CometAPI model ID. A missing version segment or incorrect base URL is a documented setup failure.
  • Keep SDK authentication in a separate server-side boundary. Pass the configured client into the visual request function instead of duplicating sensitive setup in feature code.
  • The request shape uses input_text and input_image content items. The example reads response.output_text, while also validating status and an empty result.
  • A model’s vision capability does not by itself prove support for the Responses route. Verify both facts with a smoke test.
  • Operational logs should retain correlation fields and measurements, not authentication material, full image locations, prompts, generated answers, or unfiltered exception text.
  • Test one controlled success and several deliberate failures before placing the client behind a public endpoint.

Sources checked

  • The CometAPI Responses API reference defines the endpoint, multimodal input array, response status, output_text, and the warning that provider parameters and response fields can vary.
  • The CometAPI guide to OpenAI SDKs shows Node.js installation, CometAPI client configuration, and common failures involving authentication, model IDs, the base URL, and its version segment.
  • The CometAPI Qwen3-VL-32B model page describes the model as multimodal and identifies visual question answering, OCR, grounding, image input, and video understanding as intended capabilities.
  • The OpenAI images and vision guide explains image analysis and the URL and Base64 data URL conventions used by the compatible API family.
  • The Qwen3-VL upstream repository independently documents visual perception, OCR, image-plus-text input, spatial reasoning, and video understanding.

Contract details to verify

Client configuration. The SDK guide requires the CometAPI base URL rather than the SDK’s unrelated default destination. Keep client construction in one server-side integration boundary so feature modules receive an authenticated client without receiving or reproducing its sensitive configuration. The guide also calls out a missing /v1 segment as a common setup error.

Model and route compatibility. The Qwen3-VL-32B page is strong evidence that the model family can perform visual tasks. Its displayed API example uses Chat Completions, however, so that page alone does not establish Responses compatibility. Select the model from the current catalog, call it through POST /v1/responses, and keep it only after the visual fixture succeeds. This distinction prevents a capability claim from becoming an unsupported endpoint claim.

Input shape. The Responses reference accepts an array of input items for multimodal content. The client sends one user item whose content contains input_text and input_image. Preserve those names exactly. Validate the question locally, and apply an application-level HTTPS rule before sending a remote image.

Image transport. The images and vision guide describes remote image URLs and Base64 data URLs. A remote URL keeps the example compact, while a data URL can carry locally read bytes. Whichever transport you choose, test it with the selected CometAPI model and route. Do not log a complete URL because paths and query strings may contain user-specific information.

Response interpretation. The Responses reference shows id, status, an output array, and output_text. The sample copies id and status before validation, rejects a non-completed status or empty output text, and returns the answer to its caller. If you need to inspect output items instead of the convenience field, read the response object guide before adding assumptions to your parser.

Storage and optional parameters. The reference lists store with a default of true and warns that provider support varies. Decide whether storage is suitable for your image workflow, then verify the chosen setting with the exact model. Add optional parameters one at a time so a provider-specific rejection is easy to isolate.

Logging boundary. Log event, outcome, stage, model, http_status, request_id, response_id, response_status, image_host, character counts, and duration_ms. Keep authentication material, complete image URLs, image bytes, questions, answers, and raw exception bodies outside routine operational logs.

Failure modes

Authentication is rejected. The SDK guide identifies HTTP 401 as an authentication-configuration problem. Confirm that the server-side client boundary loaded the expected runtime configuration and targets CometAPI. Never print sensitive configuration while diagnosing it.

The SDK calls the wrong service. If the CometAPI base URL is absent or misspelled, the SDK may use an unintended default. If the /v1 segment is missing, the guide identifies that as another common failure. Check configuration before changing request fields.

The model ID is invalid or stale. Model catalogs change, and the SDK guide lists an invalid model ID as a common error. Reconfirm the current identifier and avoid silently substituting a text-only model, because a fallback can return fluent text without processing the image.

The model and route do not share the required capability. A catalog page can establish visual capability while showing a different endpoint family. If the Responses request rejects the image item or returns a provider-specific field shape, remove optional parameters, confirm the route, and rerun the smallest fixture.

The image cannot be retrieved or parsed. Preflight the application-controlled URL, require HTTPS as a local policy, and use a stable fixture. Treat redirects, access controls, expired links, or unsupported content as input failures rather than model-quality failures.

The request succeeds without usable text. A completed HTTP exchange can still produce a non-completed response status or no output_text. The sample converts both conditions into failures while preserving the response ID and status captured from the response. Do not log the full response until its contents have been reviewed for sensitive data.

A transient failure is retried without a budget. Network failures, throttling, and server-side errors need capped attempts, delay, and an overall deadline. The sample only marks potential retry candidates. Add client-side timeout handling before enabling automated retries.

Logs become a second copy of user content. Full image URLs, prompts, image bytes, answers, and raw errors can expose more than an operator needs. Log the host, lengths, stage, identifiers, and status instead. Keep detailed payload inspection in a controlled diagnostic path with explicit retention rules.

FAQ

Can I send a Base64 image instead of a remote URL?

Yes. The refetched images and vision guide documents both remote URLs and Base64 data URL conventions. The CometAPI Responses reference documents image items, but provider support can vary, so run the same controlled fixture through your chosen model before standardizing on a data URL payload.

Why does the sample not hardcode qwen3-vl-32b?

The CometAPI model page and upstream repository support the claim that Qwen3-VL is capable of visual question answering and OCR. The displayed CometAPI model example uses Chat Completions, though. Requiring the model ID as a function argument forces the deployment to record a model that has separately passed a Responses compatibility test.

Why does the function receive a configured client?

Client construction includes authentication concerns that should remain in one server-side boundary. Dependency injection lets the visual request code focus on multimodal input, output validation, and safe logging without duplicating sensitive setup or making it available to feature-level logs.

Should the full image URL be logged?

No. The hostname is usually enough to distinguish an asset host from an application problem. Paths and query strings can identify users, files, or temporary access grants. The sample records image_host and omits the rest.

Should the generated answer be written to the operational log?

Treat the answer as application data. The helper returns it to the caller but records only answer_chars in the operational event. If a CLI needs to show the answer, its explicit outer command can render the returned value. If the product needs answer retention, define that storage separately from infrastructure logging.

Can I use Chat Completions instead?

CometAPI’s Responses documentation says Responses extends Chat Completions with additional capabilities. The best endpoint still depends on the model and application contract. Compare the endpoint families, then keep one request and one parser rather than switching silently at runtime.

What should an integration test assert?

Use a non-sensitive image with a known visual fact. Assert that the response completes, output text is nonempty, and the answer mentions the expected fact. Also assert that the success log contains only approved fields. Negative tests should cover missing input, a missing configured client, an invalid model ID, and a simulated empty output. A test double should also confirm that a non-completed response logs its response ID and status.

What should I verify before using sensitive images?

Review image transport, provider compatibility, storage behavior, logging, retention, and access controls. The Responses reference lists storage behavior and warns that providers differ. Make those choices explicit before expanding beyond controlled fixtures.

Reader next step

Start with one controlled image and one question whose answer is obvious. Configure the SDK client inside your server-side integration boundary, select a currently available vision model, and run the function through both the happy path and the deliberate invalid-model path. Do not connect it to user uploads until response validation, sanitized logging, storage behavior, timeouts, and retry limits are all explicit.

When that local contract test is ready, Start with CometAPI .