Audience: FDEs and developers of customer model or metering platforms.
Audience: FDEs and developers of customer model or metering platforms. Call direction: QwenWork server → Customer API.
This is the entry point for BYOK integration. Quota and usage SPI names, fields, examples and acceptance criteria follow the existing BYOK limits and usage documentation and current code. Model and search integration follows the current Model BYOK and search APIs protocol. All examples use synthetic data; replace organizations, users, current periods and credentials for real integration testing.
The model module is required: connect at least one primary Agent Chat model. Implement specialized models and search according to enabled capabilities. The quota and usage SPI is optional. When enabled, its eight endpoints form one BYOK limits and usage group sharing a URL, token and switch.
The entries below reuse existing endpoint names. Complete protocols and examples are maintained only in their source guides.
Models use complete endpoints; reference paths can be customized within the selected protocol's constraints. The quota and usage SPI appends fixed paths to the base URL. Model capabilities may share URLs and asynchronous query templates; customers do not need 18 separate URLs.
You do not need to implement model subscription queries, user creation, department aggregation, CSV exports, Console/IAM Internal APIs, configuration publishing or per-call accounting callbacks. License/IAM continues to supply product subscriptions.
Acceptance order: authentication and network → eight-endpoint fields → enable/disable configuration → quota/model/statistics flow for the same user → failure retries and cycle transitions → customer environment acceptance. Verify the identity and customer ledger for quota-limited model calls; a successful connectivity check alone is insufficient. Deliver credentials separately through a secure channel.
The model and search guide defines customer-service requests, responses, asynchronous tasks and errors. Subsequent quota and usage SPI changes remain governed by the existing chapters and code; do not maintain duplicate versions here.
Static documentation checks do not replace customer-network tests, actual quota writes, model quality checks or deployment acceptance.
Reading guide
| Document | Contents |
|---|---|
| This guide | Complete SPI inventory, dependencies and delivery requirements |
| Quota and usage SPI integration overview | Overview of the eight existing SPI endpoints and call relationships |
| Quick start | URLs, authentication, identities and configuration |
| Usage APIs | Dates, organization usage, member usage and trends |
| Quota APIs | Rules and periods, member quotas, limit writes and organization quota |
| Validation and troubleshooting | Integration checklist, errors and diagnosis |
| Model BYOK and search APIs | Chat, image, video, music, ASR and search protocols, with streaming and asynchronous examples |
Complete SPI inventory
The model module is required: connect at least one primary Agent Chat model. Implement specialized models and search according to enabled capabilities. The quota and usage SPI is optional. When enabled, its eight endpoints form one BYOK limits and usage group sharing a URL, token and switch.
Models and search
| Capability | Method / reference path | Requirements and details |
|---|---|---|
| Chat, VL and text polishing | POST to a complete Chat URL, such as /v1/chat/completions | Primary Chat required; model guide §3 |
| Synchronous image generation/editing | POST /api/v1/services/aigc/multimodal-generation/generation | When Sync is selected; model guide §5.2 and §5.3 |
| Asynchronous image submission | POST /api/v1/services/aigc/image-generation/generation | When Async is selected, also implement image/video task queries; model guide §5.2 and §5.4 |
| Image/video task query | GET using the configured …/{task_id} template | Companion to asynchronous image and four-mode video submissions; model guide §4, §5.4 and §6 |
| Four-mode video submission | POST /api/v1/services/aigc/video-generation/video-synthesis | Implement enabled modes with image/video task queries; model guide §6 |
| Synchronous music generation | POST /api/v1/services/audio/music/generation | When music is selected; no additional task query; model guide §7 |
| Realtime ASR | WS/WSS /api-ws/v1/realtime?model=… | Base64 audio and session events; model guide §8.2 |
| Streaming ASR | WS/WSS /api-ws/v1/inference | Binary audio and task events; model guide §8.1 |
| Web search | POST to the complete configured URL, such as /search/unified | When enabled; web search request; model guide §9.1 |
| Image search | POST to the complete configured URL, such as /search/multimodal | When enabled; sends only query; model guide §9.2 |
Quota and usage SPI
The entries below reuse existing endpoint names. Complete protocols and examples are maintained only in their source guides.
| Endpoint | Method and path | Responsibility | Call timing |
|---|---|---|---|
| Get latest statistics date | GET /spi/v1/usage/meta | Latest complete data date | Statistics refresh and manual connectivity check |
| Query organization usage overview | GET /spi/v1/usage/overview | Historical organization usage | Build snapshots by date and five periods |
| Query member usage list | GET /spi/v1/usage/members | Historical member usage | Build snapshots by reading every page |
| Query member daily usage trend | GET /spi/v1/usage/members/{external_user_id}/trend | Daily member trends | Read on demand when viewing a member's trend |
| Query quota rules and period | GET /spi/v1/quota/context | Quota constraints and current period | Validate quotas and determine period boundaries |
| Query member quotas | POST /spi/v1/quota/users/query | Applied member quotas | Explicit SDK query; the product does not require read-after-write |
| Set member limit | PUT /spi/v1/quota/users | Set one member's absolute limit | Background dispatch and retries of quota changes |
| Query organization quota | GET /spi/v1/quota/org | Real-time organization total quota and usage | Organization quota queries |
Integration flow and responsibilities
- Confirm the organization, user IDs and metering rules; configure models and search separately.
- Configure and enable BYOK limits and usage; the connectivity check calls only Get latest statistics date.
- Query quota rules and the period, set member limits and confirm results; query organization quota for the quota overview.
- Make actual model calls using the same user to verify customer-side limit enforcement.
- After the customer finalizes statistics, get the latest date and query organization and member usage for all five periods.
- The existing statistics task validates data and publishes snapshots to local PostgreSQL; pages, department statistics and exports read these snapshots.
- Member details call Query member daily usage trend on demand.
Current configuration and integration entry points
- Configuration: Console → Open Platform → Extensions → BYOK limits and usage. Configuration is stored in spi_configurations with encrypted credentials. Each new request/task reads it dynamically, while a single operation uses a fixed version. When unconfigured or disabled, K8S uses the empty implementation. When enabled, all eight endpoints use the customer SPI; other static extensions, including License, retain their existing paths.
- URL: HTTP/HTTPS, domains/IPs, ports and path prefixes are supported. HTTP warns that tokens are transmitted in plaintext. HTTPS validates certificates normally, without custom CAs or a validation bypass. Configuration, connectivity checks and actual calls share validation and do not follow redirects.
- Test connectivity: Checks only HTTP 200 from Get latest statistics date, with a maximum of 5 seconds. It does not validate JSON or the other seven endpoints, or save/enable configuration. Cluster Biz resolves .svc; the browser need not resolve it.
- Quota overview: Organization total and usage in /api/console/biz/v1/quota-overview come from Query organization quota. Rule counts and default individual limits come from local configuration. When disabled, K8S reports unsupported; when enabled, the customer response is used.
- Manual statistics synchronization: Authenticated POST /api/console/biz/v1/analytics/usage/sync-runs, with no UI button. A new or identical ds reloads and publishes all five periods; an earlier ds returns unchanged. See the synchronization notes in Usage APIs.
FDE delivery record and acceptance
| Item | Deliver or confirm |
|---|---|
| Capabilities and versions | Model scope, whether this group is enabled, both builds and this package version |
| Model URLs | Model IDs, complete URLs, protocols, query templates, authentication and supported parameters |
| General URL | One base URL/token, authorized organization UUID and customer tenant; QwenWork supplies binding_id in requests |
| User identity | External ID source, actual IAM binding, offboarding/rebinding and cross-organization isolation |
| Metering cycle | Credit definition, pricing, rounding, failed/canceled call charges, cycle boundaries and permanent quotas |
| Data service | Complete-ds readiness SLA, five periods, stable pagination, trends and retention |
| Network capacity | Biz reachability, certificates, timeouts, rate limits, asset and task expiration |
| Integration evidence | Fields for all eight endpoints, idempotent member limit writes and actual enforcement, organization quota queries, statistics publication/repeated triggers and dynamic switching |