Star Site Integration#

Use the Star public contracts. Do not call RokoAPI or any upstream provider from a frontend site, and do not reproduce point-consumption logic in the frontend.

Workflow#

Ask for or locate the assigned site_id and registered production origin.
Read [configuration.md](references/configuration.md) and implement Star Auth first.
Read [tasks.md](references/tasks.md) and [pricing.md](references/pricing.md) when the site creates model-based AI tasks. Read [chat.md](references/chat.md) whenever a selected runtime mode has task_type=chat; chat is synchronous or streaming and never uses the asynchronous /v1/tasks creation endpoint. Also read [task-collections.md](references/task-collections.md) for ordered multi-image sets with resumable per-image progress and version history. Discover models and pricing at runtime; never hard-code provider names or point costs.
Read [tools.md](references/tools.md) when the site exposes reusable features such as lyrics generation, image-to-prompt analysis, background removal, or style transfer.
Read [payments.md](references/payments.md) when the site sells subscriptions or point packs, resumes checkout after login, displays orders and receipts, or lets users cancel and restore automatic renewal.
Read [analytics.md](references/analytics.md) and enable PV/UV reporting on every public page except the auth callback.
Run every check in [verification.md](references/verification.md) before release.

Non-negotiable contracts#

Browser login goes through https://auth.starhk.uk; AI tasks go through https://task.starhk.uk.
Payment catalog, Checkout, orders, and invoices go through https://pay.starhk.uk; provider secrets and entitlement fulfillment remain server-side.
Discover payment product IDs, prices, and point or plan entitlements from the site-scoped Star Pay product catalog. Render unit_amount with currency, use entitlements for benefits, and do not hard-code amounts that can drift from the payment configuration.
Discover payment capabilities from Star Pay, then intersect them with the site's own scenario-specific display selection. The platform response defines what may be called; the frontend owns which allowed methods to show, their order, localized labels, and default choice. Never treat detected country or locale as a server authorization rule.
Every protected request carries Authorization: Bearer <access_token> and the assigned site_id.
Use a fresh UUID v4 idempotency_key for each user-initiated task and reuse it only when retrying that same action.
Poll the returned poll_url; do not construct an upstream task URL.
For a confirmed multi-image set, create one task collection and let Star Task create its child tasks. Do not loop over /v1/tasks in the browser or implement collection charging/refunds client-side.
New sites discover user-facing products from /v1/models?view=products&site_id=.... After a user selects a mode, submit that mode's exact task_model and task_type; never construct a child alias from the product ID or a suffix.
Route by execution contract after selecting a mode: task_type=chat uses POST /v1/ai/chat with input.messages; asynchronous image, video, audio, and music modes use POST /v1/tasks and poll the returned URL. Never send chat to /v1/tasks.
Model logos are supplied by Star Task. For the recommended product view, render the returned products[].icon; for the backward-compatible flat view, render models[].logo_url, which is the administrator-maintained Model Logo URL field. Never map vendors/model names to bundled frontend logos or construct a logo URL.
Treat the site-scoped response as the server-allowed runtime set. A site may show any local/CMS-configured subset of that response without changing Star Task policy; compute the UI set as runtime products ∩ site display selection, and ignore configured IDs that are absent or not callable.
Discover image modes from the selected product mode. Submit only fields and limits declared by that mode's form_schema / runtime capabilities.
Display the model catalog's unit-aware reference_price; use pricing quote cost_points for the configured estimate and task-creation cost_points as the authoritative charge. Provider routing and charging are server responsibilities.
Refresh catalog and pricing caches when model_policy_version, pricing_version, or a rule's source.expr_hash changes. Never execute an upstream billing_expr in a browser.
Star Task automatically gives a newly synchronized model its initial point price from RokoAPI's structured USD contract at 1 point = USD 0.0074; media totals round up to whole points and text Token rates retain decimals. Existing global or site prices are never overwritten, and administrators may adjust the initial price later. Frontends still use only Star Task quotes and must never call catalog sync, pricing-draft, or pricing-publish endpoints.
Discover reusable tools from /v1/tools; do not copy their hidden prompts, backend models, or prices into frontend code.
Public point charges and configured prices use 0.01-point increments, while internal settlement may retain three decimals. Display all user-facing balances, quotes, charges, and refunds with exactly two decimal places without converting API numbers into billing strings.
Store access/refresh tokens using the host project's established secure pattern. Never expose site secrets, RokoAPI keys, or admin credentials in browser code.
Treat output URLs returned by Star Task as the stable application URLs. Do not depend on temporary upstream URLs.
When a task reaches failed, surface task.error to the user. Star Task normalizes explicit prompt content-policy rejections into a user-safe Chinese message; show it in a modal, toast, or prominent error area instead of replacing it with a generic generation failure.
A payment return is not proof of fulfillment. Refresh Star Auth overview and Star Pay orders, and never grant plans or points in frontend code.
Canceling renewal is not a refund. Use the Star Pay subscription endpoint, retain the paid plan and issued points through current_period_end, and offer resume only while the Stripe subscription has not ended.

Change discipline#

Preserve the host site's existing routing, UI system, and auth state shape. Make the smallest compatible change, then verify login, refresh, task idempotency, charging, result rendering, and analytics independently.

Optional site self-service pricing#

When the site wants to manage its own prices, read references/site-pricing.md in addition to references/pricing.md. After one-time platform authorization, use a dedicated server-side SITE_PRICING_TOKEN with site-scoped permissions to preview and publish simplified prices. Do not ask the platform to manually change every price. Keep the credential outside browser code, authenticate the site's administrators, and use the runtime model ID and an explicit expected_etag. Without a delegated credential, request one-time authorization; ordinary user JWTs and site API keys cannot write prices. Publication changes backend billing; a local display-only price change is insufficient.