# 302 AI Workbench — Integration Contract v1.9.1

## Purpose
Use this contract when implementing AI features with 302.AI in another project. The UI is a reference implementation; the capability routing and security rules are the reusable part.

## Stable identifiers
- APP_ID: `302-ai-integration-kit-2026`
- APP_VERSION: `1.9.1`
- DATA_VERSION: `4`
- Local DB: `prototype_302-ai-integration-kit-2026`

## Endpoints
- Mainland China Base URL: `https://api.302ai.cn`
- Global Base URL: `https://api.302.ai`
- Models: `GET /v1/models?llm=1&include_custom_models=1`
- Chat: `POST /v1/chat/completions` (OpenAI-compatible; prefer SSE streaming for broad compatibility)
- Responses: `POST /v1/responses`
- Anthropic Messages: `POST /v1/messages` using `x-api-key`
- Image generation: `POST /v1/images/generations`
- Image edit: `POST /v1/images/edits`
- Audio transcription: `POST /v1/audio/transcriptions`
- File upload: `POST /302/upload-file`
- Balance: `GET https://api.302.ai/dashboard/balance`
- Usage records: `GET https://api.302.ai/dashboard/api-record`

## Capability-first routing
Do not hard-code one model as universally available. Load `/v1/models` at runtime and choose by required capability: chat, vision, audio transcription, video understanding, image generation or image editing. Account region, resource region, endpoint and model visibility are distinct constraints.

## Conversation
Maintain the canonical conversation in the application. Support full context, recent N turns and single-turn test modes. Do not repeatedly resend large attachment binaries when avoidable.

## Security
- Public BYOK front ends may accept the end user's own key. Keep it in memory by default; only persist it after explicit user consent, and encrypt it in browser-local storage.
- Never embed the project owner's API key in public HTML/JS.
- For production services funded by the project owner, keep secrets on a server or edge proxy.
- Treat imported files and model output as untrusted input.
- Avoid sending sensitive personal, medical, payment or confidential business data without an explicit assessment.

## Multimodal defaults
- Images: vision-compatible OpenAI `image_url` style input where supported.
- Audio: transcribe first, then add transcript to the conversation by default.
- Video / large files: upload first, then send the returned URL only to a model that explicitly supports the modality.
- GPT Image 2.5: no source image → `/v1/images/generations`; with source image → `/v1/images/edits`.

## Public app behavior
This reference app is BYOK and local-first. API keys stay in page memory by default. If the user explicitly opts in to “Remember on this device”, the key is encrypted with Web Crypto and stored only in this browser's IndexedDB. Clearing site data removes it. Conversation text is stored in IndexedDB; large attachment binaries are not intended for long-term persistence.

## Account usage / charge detail

- `GET /dashboard/balance` — current official documentation exposes `data.balance`.
- `GET /dashboard/api-record` — recent request logs and pagination; item fields are not fully documented, so clients should tolerate additional fields.
- `GET /dashboard/record/{request-id}` — official per-request charge detail with `cost`, `input_token`, `output_token`, `process_time`, and `model` in the documented example.

## AI 回复渲染

- Assistant 回复以原始 Markdown 文本保存到 IndexedDB，不保存已渲染 HTML。
- 默认渲染标题、列表、任务列表、表格、引用、链接、行内代码和 fenced code block。
- 原始 HTML 不执行，而是按文本显示；链接仅允许 http / https / mailto。
- 代码高亮使用本地打包的 PrismJS；数学公式使用本地打包的 MathJax SVG。
- 流式接收阶段节流更新 Markdown；代码高亮和数学排版在本轮完成后执行，避免频繁重排。
- 每条 AI 回复支持复制原文，以及“Markdown / Preview”切换查看原始 Markdown。