DEV-COMMERCE-02-001 模型网关接口契约

The frontend never stores provider credentials or calls provider endpoints directly. Production integrations sit behind the OceanWay model gateway configured by VITE_API_BASE_URL.

List Models

GET /v1/models?capability={jobType}

The gateway may return any number of models for one tool capability.

{
  "models": [
    {
      "id": "provider-model-id",
      "name": "Display name",
      "provider": "Provider name",
      "capability": "remove-background",
      "media": "image",
      "status": "available",
      "version": "optional-version",
      "supportedParameters": ["edge-mode", "edge-refine"]
    }
  ]
}

Supported capability values are defined by JOB_TYPES in src/domain/types.ts. The initial visible set is:

1. remove-background
2. remove-white-background
3. video-generator
4. edit-with-ai
5. product-beautifier
6. product-staging
7. ai-background
8. shooting-list

Create Job

POST /v1/jobs

{
  "type": "remove-background",
  "inputAssetId": "asset-id",
  "modelId": "provider-model-id",
  "prompt": "optional natural language instruction",
  "parameters": {
    "edge-mode": "fine",
    "edge-refine": 72,
    "transparent-output": true
  }
}

The parameters object is intentionally generic. The gateway maps it to provider-specific request fields and rejects unsupported parameters with a normal API error response.

Job Lifecycle

• GET /v1/jobs/:id
• POST /v1/jobs/:id/cancel

Job responses use queued, running, succeeded, failed, or cancelled. Successful jobs may return outputUrl or multiple outputUrls.

Runtime Modes

• VITE_DATA_MODE=mock uses deterministic local jobs and a multi-model mock registry.
• VITE_DATA_MODE=api uses the gateway endpoints above.
• Access tokens are read from the in-memory AuthClient; refresh sessions rely on the central HttpOnly cookie.