Integrate an existing application

An existing application usually already has a UI, business API, database, and job queue. Keep those layers and add a GridNexa provider where the application currently calls a model service.

The client continues to call the application's business API. The backend converts business actions into capability requests and writes results back into its own tasks and assets.

Keep model credentials, routing, input uploads, and task polling on the server. The client sees only application fields and application status, preserving existing authorization, audit, retry, and data models.

Web or mobile client
  -> your application API
  -> business service / job queue
  -> GridNexa provider adapter
  -> POST /v1/invoke
  -> platform task and artifacts
  -> your application data and response

Find every business action that triggers a model request. Record its inputs, return value, timeout, retry behavior, and persistence path, then map it to a GridNexa capability.

• Use chat for conversation and assisted drafting; text.generate covers standalone text generation.
• Use image.generate without references and image.edit with source or reference images.
• Use video.generate without a first frame and video.image_to_video with a first frame.
• A workflow can call several capabilities in sequence; orchestration remains in the application.

Centralize the base URL, authentication, idempotency, error parsing, and HTTP 200/202 branches in one provider. Business services pass capability, input, parameters, and execution mode.

The provider keeps requestId and task_id for diagnostics. Authorization headers, presigned URL signatures, and raw API keys stay out of logs.

async function runCapability(request) {
  const url = process.env.GRIDNEXA_AI_BASE_URL + '/v1/invoke';
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.GRIDNEXA_AI_API_KEY,
      'Content-Type': 'application/json',
      'Idempotency-Key': request.idempotencyKey,
    },
    body: JSON.stringify({
      capability: request.capability,
      input: request.input,
      parameters: request.parameters,
      execution: {mode: request.mode},
    }),
  });

  if (!response.ok) throw await toGridNexaError(response);
  return response.json();
}

Convert application fields into the public contract: conversation history becomes messages, canvas dimensions become aspect_ratio, and references become role-labeled media inputs.

The business layer still owns call order, prompt templates, approval points, and persistence. GridNexa executes each capability call.

business action        GridNexa capability
-------------------------------------------------
assistant / rewrite    -> chat or text.generate
create image           -> image.generate
edit reference image   -> image.edit
create video           -> video.generate
animate first frame    -> video.image_to_video

When media lives on disk, object storage, or in a database, the worker reads it, completes the three-step input upload, and sends the ready asset_id with the invocation.

Keep the application's asset ID separate from the platform input asset ID: one identifies business data and the other authorizes validated model input.

Track application jobs and platform tasks separately. The application job describes user-visible progress; platform_task_id identifies one GridNexa execution.

After 202, persist status_url, result_url, and retry_after_seconds. A background worker polls, reads artifacts, persists required files, and then updates the application job.

application_job_id  -> ID shown to your user
platform_task_id     -> GridNexa asynchronous task
idempotency_key      -> stable key for one billable attempt
status_url           -> platform execution status
result_url           -> platform output and artifacts

Map platform codes into application error types while retaining code, message, and requestId. Return validation errors directly and retry rate limits or transient failures according to Retry-After and application policy.

Use one stable Idempotency-Key for each billable attempt. Reuse it after a network timeout so duplicate generation or billing is less likely.

GRIDNEXA_AI_BASE_URL and GRIDNEXA_AI_API_KEY come from backend API or Worker secret configuration. Browser requests, frontend bundles, task messages, and ordinary business databases do not store the raw key.

For a published application, the model API key and Endpoint credential remain separate: one calls models and the other grants access to the application.

Replace the existing provider one capability at a time while keeping the UI and business API stable.

• Integrate chat or text.generate and verify synchronous output and usage.
• Integrate image.generate, including 202 polling and artifact download.
• Add input assets before exposing image.edit or image-to-video.
• Integrate video capabilities and test long timeouts and large downloads.
• Add provider switching, health checks, and observability to the release process.

Run at least one real business request from the application API through result persistence.

• No developer API key appears in client requests.
• Each business action maps to the intended capability.
• Synchronous calls retain requestId, output, and usage.
• Asynchronous calls retain task_id and handle every terminal state.
• Inputs are ready before invocation and artifacts are persisted before download URLs expire.
• A retry with the same Idempotency-Key does not create a second execution.