Custom Integrations

Use this document before changing non-generic provider/platform behavior. If a user request includes a custom keyword such as 元界, mozheAPI, or 智能配置 API, first check long-term memory and the relevant rows in the Codex docs, then verify the current source/runtime before editing.

Required Workflow

Search existing long-term memory and this docs folder for the exact custom keyword.
Read the matching feature, bug, API, or architecture entry before touching code.
Treat custom provider/platform behavior as a named integration boundary, not as generic fallback logic.
Preserve the provider-specific contract unless the user explicitly changes that contract.
When a fix reveals a new reusable rule, update this file or the matching Codex doc in the same change set.
If the rule is durable across future sessions, write it to long-term memory instead of relying only on chat context.

元界 AI

Start with src/lib/yuanjie-image-model-templates.ts, src/lib/yuanjie-video-model-templates.ts, src/lib/yuanjie-template-installer.ts, src/lib/user-api-manifest-executor.ts, and the selected create panel.
Built-in 元界 templates are not generic OpenAI-compatible models. Their manifests may map UI fields to provider-specific params such as size, aspect_ratio, aspectRatio, imageSize, resolution, quality, images, or task polling fields.
Built-in 元界 video media requests should stay in Manifest form and should not fall back to the generic OpenAI-compatible video parser. /v1/media/generate submit bodies use only model, prompt, and params; HappyHorse text-to-video specifically sends params.resolution, params.ratio, and params.duration, then reads output.task_id and polls /v1/media/status?task_id=....
Some image models expose orientation through a size/resolution value instead of a separate aspect-ratio field. In those cases the create panel must derive the ratio from the selected option label or pixel dimensions, rather than requiring the user to write the ratio in the prompt.
元界 media submit responses may return the task identifier under nested result objects such as result.task_id, result.taskId, or result.id. The Manifest executor must extract task IDs from those nested objects before polling v1/media/status.
If 元界后台 shows a successful image but MiaoJing marks the job failed, treat it as a result-media download/persistence issue before changing submit/poll config. Check src/app/api/generate/image/route.ts, src/lib/media-storage.ts, and src/lib/remote-fetch.ts for 403, timeout, object-storage, or thumbnail errors. Result URL fetches should use browser-like headers plus limited retry, and Manifest result persistence failures should be reported as platform download/save failures, not as image-resolution mismatch.
Do not add 自动 back to controls where the user explicitly asked for explicit manual choices. Image count should default to 1 when automatic inference is not part of the requested workflow.
Admin default models must use system_api_configs.name as the frontend display name, while model_name remains the upstream request model.
When 元界 is used as a system default model, credit deduction must still follow the selected system_api_configs row's pricing through the generation job backend. New-job balance preflight should include same-user queued/running system-default jobs. Image and video create UI should display only the completed job's returned creditsCost and refresh the profile balance from creditsBalance, not a separate predicted button cost. Failed jobs must not write consume transactions.
Yuanjie image and video templates that accept reference media should render provider-facing references with $inputImages.urls, not $inputImages.dataUrls. The Manifest executor uploads data URL references into storage first, then exposes object/local-storage public URLs as $inputImages.urls while keeping raw data URLs available as $inputImages.dataUrls for multipart/file-upload manifests.
Yuanjie GPT Image 2 / GPT Image 2 official-transfer image-to-image must pass all frontend references. src/components/create/image-to-image.tsx sends the primary image as image and additional references as extraImages; src/app/api/generate/image/route.ts must normalize them into the Manifest inputImages array before calling src/lib/user-api-manifest-executor.ts.
Yuanjie video templates must stay in src/lib/yuanjie-video-model-templates.ts and map documented model-specific fields there instead of changing generic mozheAPI/custom-API request builders. Current documented special mappings include sora-2.params.input_reference, wan2.6-cankaosheng.params.reference_urls, wan2.6-shouzheng.params.img_url, kling-v3-omni-shouweizhen.params.image/image_tail, happyhorse-r2v.params.ratio, grok-video-3.params.size, and veo3.1.params.generation_mode/enhance_prompt/enable_upsample.
Existing admin-created 元界 system rows may have an empty manifest_path and a submit endpoint in api_url. src/lib/yuanjie-system-manifest.ts is responsible for exposing built-in frontend capabilities for those rows and repairing them at generation time by writing the missing Manifest and normalizing api_url to the 元界 base URL. This repair must remain scoped to 元界 provider/model-group checks and must not rewrite mozheAPI.
元界价格/计费方式同步 is manual only. Admins trigger it from the 系统默认模型 provider view; the route is /api/admin/system-apis/yuanjie-pricing and the logic lives in src/lib/yuanjie-pricing-sync.ts. It updates only existing 元界 image/video rows, accepting provider spellings such as 元界 AI/元界AI and yuanjie-* model groups, synchronizing billing_mode and a 元界计费同步 price note from local built-in template metadata. It must not delete, create, or rewrite mozheAPI rows, generic smart-import rows, API keys, Manifest paths, or administrator-entered numeric prices.

Agnes AI

Start with src/lib/agnes-model-templates.ts, src/lib/agnes-template-installer.ts, src/app/api/admin/system-apis/agnes-capabilities/route.ts, and src/components/admin/api-management-tab.tsx.
Agnes built-in templates belong to the 系统默认模型 management flow. Do not expose them as a generic 智能配置 API import; keep one system API row per model and one independent system-api-manifests/<systemApiId>.json file for each image/video row.
The API base is https://apihub.agnes-ai.com. Image models agnes-image-2.1-flash and agnes-image-2.0-flash use POST /v1/images/generations with model, prompt, size, and optional top-level image: string[] for image-to-image. URL output must be requested as extra_body.response_format = "url"; do not put response_format at the top level. Read data.*.url, with data.*.b64_json as a fallback.
Video model agnes-video-v2.0 uses POST /v1/videos to create an async task and GET /agnesapi?video_id={video_id}&model_name=agnes-video-v2.0 to poll. Treat video_id, task_id, or id as the task identifier, completed as success, failed as failure, and read the final video from remixed_from_video_id, video_url, or url.
Agnes Video duration is controlled by num_frames, not a duration request field. The create route currently exposes only production-stable UI durations 3/5/10 seconds, maps them to the documented 24fps frame counts 81/121/241, and sends frame_rate: 24. Do not re-enable 18 seconds from stale Manifests or older docs until production evidence shows Agnes no longer returns upstream failed for that length; backend requests for 18 seconds should be rejected quickly with a clear user-facing message.
Agnes Video generation can spend minutes in the async task. Keep the Manifest total polling budget separate from per-request submit/poll timeouts, and treat single poll-side 502/503/504, fetch failed, or network timeouts as transient until the total budget expires.
For image-to-video, Agnes uses the top-level image field as the starting/first frame. Do not treat Agnes Video as a generic multi-reference video model unless Agnes adds a separate reference-image field.
Text/multimodal models agnes-2.0-flash and agnes-1.5-flash use OpenAI-compatible POST /v1/chat/completions; they do not need Manifest files and can be used by prompt optimization or reverse prompt through the existing system text API path.
The installer creates Agnes rows as inactive, 0-credit templates with empty API Key fields so admins can fill the Key in the existing system API edit form, review visibility/member scope, and then enable the model.

mozheAPI

Start with src/proxy.ts for iframe/embed failures before changing page components.
Third-party embedding depends on CSP frame-ancestors and X-Frame-Options; SAMEORIGIN blocks external parents even if app pages render correctly.
Keep the allowlist explicit. Do not globally weaken security headers for unrelated origins.

智能配置 API

User-level manifests must stay one model/key row to one JSON Manifest file. Do not merge multiple request configs under one user-level shared file.
Admin global default manifests can be shared through system API configuration, but generation must still resolve the selected model row and charge according to that model's pricing rules.
Imported rows should preserve manifest_path, provider/model display metadata, and per-model request templates.

9.4 KiB Raw Blame History