1118 lines
52 KiB
TypeScript
1118 lines
52 KiB
TypeScript
import { Fragment, useEffect, useMemo, useState, type CSSProperties, type FormEvent, type ReactNode } from 'react';
|
||
import type { GatewayApiKey, GatewaySkillBundleMetadata, GatewayTask } from '@easyai-ai-gateway/contracts';
|
||
import { BookOpen, Download, ExternalLink, FileJson, KeyRound, Play, Search, Send, Wrench } from 'lucide-react';
|
||
import { Badge, Button, Input, Select, Textarea } from '../components/ui';
|
||
import { getOpsManagementSkillMetadata, resolveApiAssetUrl } from '../api';
|
||
import type { ApiDocSection, LoadState, TaskForm, TaskKind } from '../types';
|
||
import { ApiKeySelect, apiKeyNoticeText, resolveSelectedApiKeyId } from './playground-shared';
|
||
|
||
interface ApiDocItem {
|
||
group: string;
|
||
key: ApiDocSection;
|
||
kind?: TaskKind;
|
||
lead: string;
|
||
method?: 'GET' | 'POST';
|
||
path?: string;
|
||
title: string;
|
||
}
|
||
|
||
interface ApiDocParam {
|
||
children?: ApiDocParam[];
|
||
name: string;
|
||
required?: boolean;
|
||
type: string;
|
||
value: string;
|
||
}
|
||
|
||
type ApiGuideSection = Extract<ApiDocSection, 'guideBaseUrl' | 'guideWebhook' | 'guideErrors' | 'guideTesting'>;
|
||
|
||
interface ApiGuideItem {
|
||
group: '指南';
|
||
key: ApiGuideSection;
|
||
lead: string;
|
||
title: string;
|
||
}
|
||
|
||
export const apiDocs: ApiDocItem[] = [
|
||
{ key: 'chat', group: '文本', kind: 'chat.completions', method: 'POST', path: '/v1/chat/completions', title: 'Chat Completions', lead: 'OpenAI 兼容的对话接口，支持本地 API Key 授权、simulation 测试和非流式/流式响应。' },
|
||
{ key: 'responses', group: '文本', kind: 'responses', method: 'POST', path: '/v1/responses', title: 'Responses', lead: 'OpenAI 兼容的 Responses 接口，原生支持 input、previous_response_id、工具调用和流式输出；不支持原生 Responses 的模型会由网关转换到 Chat Completions。' },
|
||
{ key: 'embeddings', group: '文本', kind: 'embeddings', method: 'POST', path: '/v1/embeddings', title: '文本向量 Embeddings', lead: 'OpenAI 兼容的文本向量接口，可直接用 input 数组或字符串生成 embedding，API Key 需要 embedding 权限。' },
|
||
{ key: 'reranks', group: '文本', kind: 'reranks', method: 'POST', path: '/v1/reranks', title: '文本重排序 Reranks', lead: 'OpenAI 风格的重排序接口，传入 query 和 documents 后返回 relevance_score，API Key 需要 rerank 权限。' },
|
||
{ key: 'imageGeneration', group: '图片', kind: 'images.generations', method: 'POST', path: '/v1/images/generations', title: '创建图片', lead: 'OpenAI 兼容的图片生成接口，支持 prompt、size、quality 和 simulation 测试。' },
|
||
{ key: 'imageEdit', group: '图片', kind: 'images.edits', method: 'POST', path: '/v1/images/edits', title: '编辑图片', lead: 'OpenAI 兼容的图片编辑接口，支持 image、mask、prompt 和 simulation 测试。' },
|
||
{ key: 'videoGeneration', group: '视频', kind: 'videos.generations', method: 'POST', path: '/api/v1/videos/generations', title: '生成视频', lead: '视频生成任务接口，支持文生视频、首尾帧、图片/视频/音频参考，以及时长、分辨率、画幅和声音等模型能力参数。' },
|
||
{ key: 'asyncMode', group: '异步任务', title: '异步模式', lead: '所有 AI 任务创建接口使用同一种异步开启方式：保留原接口和原请求 Body，只需增加 X-Async: true。' },
|
||
{ key: 'taskRetrieve', group: '异步任务', kind: 'tasks.retrieve', method: 'GET', path: '/api/v1/tasks/{taskID}', title: '取回任务', lead: '使用异步提交返回的 taskId 查询任务状态、结果、错误、用量、计费和执行尝试；queued、running、submitting 为进行中状态。' },
|
||
{ key: 'pricing', group: '计费', method: 'POST', path: '/api/v1/pricing/estimate', title: '价格预估', lead: '按请求体估算输入输出 token、模型倍率和折扣后的预估费用。' },
|
||
{ key: 'files', group: '文件', method: 'POST', path: '/v1/files/upload', title: '上传文件', lead: '上传在线测试所需的图片、音频或视频资源，后续请求可复用返回的文件 URL。' },
|
||
];
|
||
|
||
const guideItems: ApiGuideItem[] = [
|
||
{ key: 'guideBaseUrl', group: '指南', title: '获取 Base URL 和 API Key', lead: '确认当前部署环境的网关地址，创建 API Key，并使用 Bearer 鉴权调用公开接口。' },
|
||
{ key: 'guideWebhook', group: '指南', title: '通知设置-WebHook 参数介绍', lead: '了解任务进度 WebHook 的启用方式、回调结构、可靠投递机制和公开 API 的状态取回方式。' },
|
||
{ key: 'guideErrors', group: '指南', title: '错误码', lead: '根据 HTTP 状态、error.code、requestId 和异步任务错误字段快速定位请求失败原因。' },
|
||
{ key: 'guideTesting', group: '指南', title: '测试模式', lead: '使用 simulation 完整验证鉴权、路由、队列、限流、进度和结果归一，而不向真实供应商提交任务。' },
|
||
];
|
||
|
||
const taskKindOptions = [
|
||
['chat.completions', 'Chat'],
|
||
['responses', 'Responses'],
|
||
['embeddings', '文本向量'],
|
||
['reranks', '重排序'],
|
||
['images.generations', '生图'],
|
||
['images.edits', '图像编辑'],
|
||
['videos.generations', '视频生成'],
|
||
['tasks.retrieve', '取回任务'],
|
||
] as const;
|
||
|
||
const defaultOpsSkillMetadata: GatewaySkillBundleMetadata = {
|
||
name: 'ai-gateway-ops-management',
|
||
version: '',
|
||
displayName: 'AI Gateway 运维管理',
|
||
modules: ['model-runtime'],
|
||
fileName: 'ai-gateway-ops-management.zip',
|
||
downloadPath: '/api/v1/public/skills/ai-gateway-ops-management/download',
|
||
apiDocsJsonPath: '/api-docs-json',
|
||
apiDocsYamlPath: '/api-docs-yaml',
|
||
};
|
||
|
||
export function ApiDocsPage(props: {
|
||
activeDocSection: ApiDocSection;
|
||
apiKeySecretsById: Record<string, string>;
|
||
apiKeys: GatewayApiKey[];
|
||
canRun: boolean;
|
||
coreMessage: string;
|
||
coreState: LoadState;
|
||
selectedApiKeyId: string;
|
||
taskForm: TaskForm;
|
||
taskResult: GatewayTask | null;
|
||
onApiKeyChange: (apiKeyId: string) => void;
|
||
onCreateApiKey: () => void;
|
||
onLogin: () => void;
|
||
onDocSectionChange: (value: ApiDocSection) => void;
|
||
onSubmitTask: (event: FormEvent<HTMLFormElement>) => void;
|
||
onTaskFormChange: (value: TaskForm) => void;
|
||
}) {
|
||
const activeGuide = guideItems.find((item) => item.key === props.activeDocSection);
|
||
const currentApiDoc = apiDocs.find((item) => item.key === props.activeDocSection) ?? (activeGuide ? undefined : apiDocs[0]);
|
||
const current = activeGuide ?? currentApiDoc ?? apiDocs[0];
|
||
const [opsSkillMetadata, setOpsSkillMetadata] = useState<GatewaySkillBundleMetadata>(defaultOpsSkillMetadata);
|
||
const isFileDoc = currentApiDoc?.key === 'files';
|
||
const isTaskRetrieveDoc = currentApiDoc?.key === 'taskRetrieve';
|
||
const isAsyncModeDoc = currentApiDoc?.key === 'asyncMode';
|
||
const runnerAvailable = Boolean(currentApiDoc?.kind && currentApiDoc.method && currentApiDoc.path);
|
||
const apiKeyNotice = apiKeyNoticeText(props.apiKeys, props.apiKeySecretsById);
|
||
const activeApiKeyId = resolveSelectedApiKeyId(props.apiKeys, props.apiKeySecretsById, props.selectedApiKeyId);
|
||
const bodyExample = useMemo(
|
||
() => requestBodyExample(props.taskForm, currentApiDoc?.key ?? 'chat'),
|
||
[currentApiDoc?.key, props.taskForm],
|
||
);
|
||
const runnerPath = currentApiDoc?.path
|
||
? isTaskRetrieveDoc
|
||
? currentApiDoc.path.replace('{taskID}', props.taskForm.taskId?.trim() || '{taskID}')
|
||
: currentApiDoc.path
|
||
: '';
|
||
|
||
useEffect(() => {
|
||
if (currentApiDoc?.kind && props.taskForm.kind !== currentApiDoc.kind) {
|
||
props.onTaskFormChange(defaultTaskForDoc(currentApiDoc.kind, props.taskForm, props.taskResult));
|
||
}
|
||
}, [currentApiDoc?.kind, props.taskForm.kind, props.taskResult?.id]);
|
||
|
||
useEffect(() => {
|
||
let active = true;
|
||
getOpsManagementSkillMetadata()
|
||
.then((metadata) => {
|
||
if (active) setOpsSkillMetadata(metadata);
|
||
})
|
||
.catch(() => {
|
||
// Keep stable public fallback paths visible when metadata is temporarily unavailable.
|
||
});
|
||
return () => {
|
||
active = false;
|
||
};
|
||
}, []);
|
||
|
||
function handleSubmit(event: FormEvent<HTMLFormElement>) {
|
||
if (!runnerAvailable) {
|
||
event.preventDefault();
|
||
return;
|
||
}
|
||
if (!props.canRun) {
|
||
event.preventDefault();
|
||
props.onLogin();
|
||
return;
|
||
}
|
||
props.onSubmitTask(event);
|
||
}
|
||
|
||
function handleDocClick(item: ApiDocItem) {
|
||
if (item.kind) {
|
||
props.onTaskFormChange(defaultTaskForDoc(item.kind, props.taskForm, props.taskResult));
|
||
}
|
||
props.onDocSectionChange(item.key);
|
||
}
|
||
|
||
function handleGuideClick(item: ApiGuideItem) {
|
||
props.onDocSectionChange(item.key);
|
||
}
|
||
|
||
function handleKindChange(kind: TaskKind) {
|
||
props.onTaskFormChange(defaultTaskForDoc(kind, props.taskForm, props.taskResult));
|
||
const nextSection = docSectionForKind(kind);
|
||
if (nextSection !== props.activeDocSection) {
|
||
props.onDocSectionChange(nextSection);
|
||
}
|
||
}
|
||
|
||
return (
|
||
<div className="apiDocsShell">
|
||
<aside className="docsSidebar">
|
||
<div className="docsBrand">
|
||
<BookOpen size={19} />
|
||
<strong>API Docs</strong>
|
||
</div>
|
||
<label className="docsSearch">
|
||
<Search size={15} />
|
||
<input placeholder="搜索" />
|
||
</label>
|
||
<DocsGroup
|
||
title="指南"
|
||
items={guideItems.map((item) => ({
|
||
active: item.key === props.activeDocSection,
|
||
title: item.title,
|
||
onClick: () => handleGuideClick(item),
|
||
}))}
|
||
/>
|
||
{groupDocs(apiDocs).map((group) => (
|
||
<DocsGroup
|
||
key={group.title}
|
||
title={group.title}
|
||
items={group.items.map((item) => ({
|
||
active: item.key === props.activeDocSection,
|
||
method: item.method,
|
||
title: item.title,
|
||
onClick: () => handleDocClick(item),
|
||
}))}
|
||
/>
|
||
))}
|
||
</aside>
|
||
|
||
<main className="docsArticle">
|
||
<p className="eyebrow">{current.group}</p>
|
||
<h1>{current.title}</h1>
|
||
{currentApiDoc?.method && currentApiDoc.path && (
|
||
<div className="endpointBar">
|
||
<MethodBadge method={currentApiDoc.method} />
|
||
<code>{currentApiDoc.path}</code>
|
||
</div>
|
||
)}
|
||
<p className="docsLead">{current.lead}</p>
|
||
|
||
{isAsyncModeDoc ? (
|
||
<DocDetails section="asyncMode" />
|
||
) : currentApiDoc ? (
|
||
<>
|
||
{!isTaskRetrieveDoc && <OpsManagementSkillCard metadata={opsSkillMetadata} />}
|
||
|
||
<section className="paramCard">
|
||
<header>
|
||
<h2>Header 参数</h2>
|
||
<Button type="button" variant="secondary" size="sm">生成代码</Button>
|
||
</header>
|
||
{currentApiDoc.method !== 'GET' && <ParamRow name="Content-Type" type="string" required value={isFileDoc ? 'multipart/form-data' : 'application/json'} />}
|
||
<ParamRow name="Accept" type="string" required value="application/json" />
|
||
<ParamRow name="Authorization" type="string" required value={authorizationDescription(currentApiDoc.key)} />
|
||
{supportsAsyncMode(currentApiDoc.key) && (
|
||
<ParamRow name="X-Async" type="boolean" value="设为 true 后立即返回 202 和 taskId；省略时按接口默认方式执行。" />
|
||
)}
|
||
</section>
|
||
|
||
<section className="paramCard">
|
||
<header>
|
||
<h2>{isTaskRetrieveDoc ? 'Path 参数' : 'Body 参数'}</h2>
|
||
{!isTaskRetrieveDoc && <Badge variant="outline">{isFileDoc ? 'multipart/form-data' : 'application/json'}</Badge>}
|
||
</header>
|
||
{isTaskRetrieveDoc ? (
|
||
<ParamRow name="taskID" type="string" required value="异步提交响应中的 taskId，也可直接使用 next.detail 返回的地址。" />
|
||
) : isFileDoc ? (
|
||
<>
|
||
<ParamRow name="file" type="file" required value="multipart 文件字段" />
|
||
<ParamRow name="source" type="string" value="上传来源标记" />
|
||
</>
|
||
) : (
|
||
<ParamRows rows={bodyParamRows(currentApiDoc.key)} />
|
||
)}
|
||
</section>
|
||
|
||
{isTaskRetrieveDoc && <TaskResponseSchema />}
|
||
<DocDetails section={currentApiDoc.key} />
|
||
</>
|
||
) : activeGuide ? (
|
||
<GuideDetails onCreateApiKey={props.onCreateApiKey} section={activeGuide.key} />
|
||
) : null}
|
||
</main>
|
||
|
||
<aside className="docsRunner">
|
||
{currentApiDoc?.method && currentApiDoc.path && !isAsyncModeDoc ? <form onSubmit={handleSubmit}>
|
||
<header>
|
||
<strong>在线运行</strong>
|
||
<Button type="submit" size="sm" disabled={!runnerAvailable || (props.canRun && props.coreState === 'loading')}>
|
||
<Send size={14} />
|
||
{!runnerAvailable ? '暂不支持' : props.canRun ? '发送' : '登录'}
|
||
</Button>
|
||
</header>
|
||
<div className="runnerEndpoint">
|
||
<MethodBadge method={currentApiDoc.method} />
|
||
<span>{runnerPath}</span>
|
||
</div>
|
||
<label className="shLabel">
|
||
API Key
|
||
<ApiKeySelect
|
||
apiKeySecretsById={props.apiKeySecretsById}
|
||
apiKeys={props.apiKeys}
|
||
selectedApiKeyId={activeApiKeyId}
|
||
onApiKeyChange={props.onApiKeyChange}
|
||
/>
|
||
</label>
|
||
{apiKeyNotice && (
|
||
<div className="docsKeyNotice">
|
||
<span>{apiKeyNotice}</span>
|
||
<Button type="button" size="sm" variant="secondary" onClick={props.onCreateApiKey}>
|
||
<KeyRound size={14} />
|
||
创建 Key
|
||
</Button>
|
||
</div>
|
||
)}
|
||
{runnerAvailable ? (
|
||
<>
|
||
<label className="shLabel">
|
||
能力
|
||
<Select value={props.taskForm.kind} onChange={(event) => handleKindChange(event.target.value as TaskKind)}>
|
||
{taskKindOptions.map(([value, label]) => (
|
||
<option value={value} key={value}>{label}</option>
|
||
))}
|
||
</Select>
|
||
</label>
|
||
{isTaskRetrieveDoc ? (
|
||
<label className="shLabel">
|
||
Task ID
|
||
<Input
|
||
placeholder="输入异步提交返回的 taskId"
|
||
value={props.taskForm.taskId ?? ''}
|
||
onChange={(event) => props.onTaskFormChange({ ...props.taskForm, taskId: event.target.value })}
|
||
/>
|
||
</label>
|
||
) : (
|
||
<label className="shLabel">
|
||
请求 Body
|
||
<Textarea value={bodyExample} onChange={(event) => props.onTaskFormChange(parseBody(event.target.value, props.taskForm))} />
|
||
</label>
|
||
)}
|
||
<Button type="submit" disabled={props.canRun && props.coreState === 'loading'}>
|
||
<Play size={15} />
|
||
{!props.canRun ? '登录后运行' : props.coreState === 'loading' ? '运行中' : '运行测试'}
|
||
</Button>
|
||
</>
|
||
) : (
|
||
<div className="docsRunnerUnavailable">该接口暂未接入在线运行，请使用上方 Swagger 定义生成调用代码。</div>
|
||
)}
|
||
</form> : (
|
||
<section className="docsGuideAside">
|
||
<header><strong>{isAsyncModeDoc ? '能力说明' : '指南导航'}</strong></header>
|
||
<div>
|
||
<span>当前章节</span>
|
||
<strong>{current.title}</strong>
|
||
<p>{isAsyncModeDoc ? '异步模式不改变原接口的请求参数，只改变任务提交后的等待和响应方式。' : '使用左侧目录切换其他指南或 API 接口，浏览器前进、后退可保持当前章节。'}</p>
|
||
</div>
|
||
</section>
|
||
)}
|
||
{currentApiDoc?.method && currentApiDoc.path && !isAsyncModeDoc && <section className="runnerResult">
|
||
<strong>返回结果</strong>
|
||
{props.taskResult ? (
|
||
<pre>{JSON.stringify(isTaskRetrieveDoc ? props.taskResult : props.taskResult.result ?? props.taskResult, null, 2)}</pre>
|
||
) : (
|
||
<div className="emptyState">
|
||
<span>点击发送获取返回结果</span>
|
||
</div>
|
||
)}
|
||
{props.coreMessage && <p>{props.coreMessage}</p>}
|
||
</section>}
|
||
</aside>
|
||
</div>
|
||
);
|
||
}
|
||
|
||
function OpsManagementSkillCard(props: { metadata: GatewaySkillBundleMetadata }) {
|
||
const modules = props.metadata.modules.map(skillModuleLabel).join('、');
|
||
return (
|
||
<section className="agentResourceCard">
|
||
<div className="agentResourceIcon">
|
||
<Wrench size={22} />
|
||
</div>
|
||
<div className="agentResourceContent">
|
||
<div className="agentResourceTitle">
|
||
<div>
|
||
<p className="eyebrow">Agent 运维资源</p>
|
||
<h2>{props.metadata.displayName}</h2>
|
||
</div>
|
||
<Badge variant="outline">{props.metadata.version ? `v${props.metadata.version}` : '最新版本'}</Badge>
|
||
</div>
|
||
<p>用于让 Agent 安全操作厂商、基础模型、定价、运行策略、平台、平台模型和 universal 自定义平台。</p>
|
||
<div className="agentResourceModules">
|
||
<span>当前模块</span>
|
||
<strong>{modules || '模型运行时'}</strong>
|
||
</div>
|
||
<div className="agentResourceActions">
|
||
<Button asChild size="sm">
|
||
<a href={resolveApiAssetUrl(props.metadata.downloadPath)}>
|
||
<Download size={14} />
|
||
下载 SKILL
|
||
</a>
|
||
</Button>
|
||
<Button asChild size="sm" variant="secondary">
|
||
<a href={resolveApiAssetUrl(props.metadata.apiDocsJsonPath)} rel="noreferrer" target="_blank">
|
||
<FileJson size={14} />
|
||
Swagger JSON
|
||
</a>
|
||
</Button>
|
||
<Button asChild size="sm" variant="outline">
|
||
<a href={resolveApiAssetUrl(props.metadata.apiDocsYamlPath)} rel="noreferrer" target="_blank">
|
||
<ExternalLink size={14} />
|
||
Swagger YAML
|
||
</a>
|
||
</Button>
|
||
<a
|
||
className="agentResourceMetadataLink"
|
||
href={resolveApiAssetUrl('/api/v1/public/skills/ai-gateway-ops-management/metadata')}
|
||
rel="noreferrer"
|
||
target="_blank"
|
||
>
|
||
查看 metadata
|
||
</a>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
);
|
||
}
|
||
|
||
function skillModuleLabel(module: string) {
|
||
if (module === 'model-runtime') return '模型运行时';
|
||
return module;
|
||
}
|
||
|
||
function DocsGroup(props: {
|
||
items: Array<{ active?: boolean; method?: ApiDocItem['method']; onClick?: () => void; title: string }>;
|
||
title: string;
|
||
}) {
|
||
return (
|
||
<section className="docsGroup">
|
||
<h3>{props.title}</h3>
|
||
{props.items.map((item) => (
|
||
<button type="button" data-active={item.active} key={item.title} onClick={item.onClick}>
|
||
<span>{item.title}</span>
|
||
{item.method && <MethodBadge method={item.method} />}
|
||
</button>
|
||
))}
|
||
</section>
|
||
);
|
||
}
|
||
|
||
function ParamRows(props: { depth?: number; parentPath?: string; rows: ApiDocParam[] }) {
|
||
const depth = props.depth ?? 0;
|
||
const parentPath = props.parentPath ?? '';
|
||
|
||
return props.rows.map((row) => {
|
||
const path = parentPath ? `${parentPath}.${row.name}` : row.name;
|
||
return (
|
||
<Fragment key={path}>
|
||
<ParamRow {...row} depth={depth} />
|
||
{row.children?.length ? (
|
||
<ParamRows depth={depth + 1} parentPath={path} rows={row.children} />
|
||
) : null}
|
||
</Fragment>
|
||
);
|
||
});
|
||
}
|
||
|
||
function ParamRow(props: ApiDocParam & { depth?: number }) {
|
||
const depth = props.depth ?? 0;
|
||
const nameStyle: CSSProperties = depth ? { paddingLeft: `${depth * 20}px` } : {};
|
||
const markerStyle: CSSProperties = depth ? { left: `${(depth - 1) * 20 + 3}px` } : {};
|
||
|
||
return (
|
||
<div className="paramRow" data-depth={depth} data-nested={depth > 0 ? 'true' : undefined}>
|
||
<div className="paramName" style={nameStyle}>
|
||
{depth > 0 && <span aria-hidden="true" className="paramTreeMarker" style={markerStyle} />}
|
||
<code>{props.name}</code>
|
||
</div>
|
||
<span>{props.type}</span>
|
||
<p>{props.value}</p>
|
||
<em>{props.required ? '必需' : '可选'}</em>
|
||
</div>
|
||
);
|
||
}
|
||
|
||
function GuideDetails(props: { onCreateApiKey: () => void; section: ApiGuideSection }) {
|
||
if (props.section === 'guideBaseUrl') {
|
||
return (
|
||
<>
|
||
<GuideSection title="1. 确认 Base URL">
|
||
<p>Base URL 由当前 Gateway 部署环境提供。将接口文档中的路径拼接到 Base URL 后调用，不要重复添加末尾斜杠。</p>
|
||
<pre>{`export EASYAI_BASE_URL="https://your-gateway.example.com"\ncurl "$EASYAI_BASE_URL/healthz"`}</pre>
|
||
</GuideSection>
|
||
<GuideSection title="2. 创建并使用 API Key">
|
||
<p>登录后在“用户工作台 → API Key”创建 Key，并为它分配实际需要的 chat、embedding、rerank、image 或 video 权限。密钥只在创建或重置时完整展示，请立即安全保存。</p>
|
||
<div className="docsGuideActions">
|
||
<Button type="button" size="sm" onClick={props.onCreateApiKey}>
|
||
<KeyRound size={14} />
|
||
前往创建 API Key
|
||
</Button>
|
||
</div>
|
||
<pre>{`Authorization: Bearer sk-...\nContent-Type: application/json\nAccept: application/json`}</pre>
|
||
</GuideSection>
|
||
</>
|
||
);
|
||
}
|
||
|
||
if (props.section === 'guideWebhook') {
|
||
return (
|
||
<>
|
||
<GuideSection title="任务进度 WebHook">
|
||
<p>Gateway 的任务进度 WebHook 由部署管理员统一配置，用于把任务事件可靠投递到业务服务；它不是公开请求中可任意覆盖的回调地址。</p>
|
||
<pre>{`TASK_PROGRESS_CALLBACK_ENABLED=true\nTASK_PROGRESS_CALLBACK_URL=https://service.example.com/internal/task-progress`}</pre>
|
||
<p>每次状态变化会先写入任务事件和 callback outbox，再异步投递。失败不会阻塞任务执行，并会按 outbox 策略重试。</p>
|
||
</GuideSection>
|
||
<GuideSection title="回调 Body">
|
||
<pre>{`{\n "taskId": "9f4d8f3d-...",\n "seq": 3,\n "eventType": "progress",\n "status": "running",\n "phase": "generating",\n "progress": 0.6,\n "message": "任务处理中",\n "payload": {},\n "simulated": false,\n "createdAt": "2026-07-17T07:00:00Z"\n}`}</pre>
|
||
<p>公开 API 客户端无需依赖 WebHook：异步提交后可直接使用 <code>next.detail</code> 查询任务，或使用 <code>next.events</code> 订阅进度事件。</p>
|
||
</GuideSection>
|
||
</>
|
||
);
|
||
}
|
||
|
||
if (props.section === 'guideErrors') {
|
||
return (
|
||
<>
|
||
<GuideSection title="同步请求错误结构">
|
||
<pre>{`{\n "error": {\n "message": "api key scope does not allow this capability",\n "status": 403,\n "code": "forbidden"\n }\n}`}</pre>
|
||
<p>先判断 HTTP 状态，再读取 <code>error.code</code> 和 <code>error.message</code>；响应中包含 <code>requestId</code> 时请一并保存，便于关联上游请求和运行日志。</p>
|
||
</GuideSection>
|
||
<section className="paramCard docsDetailCard">
|
||
<header><h2>常见状态与处理方式</h2></header>
|
||
<div className="docsStatusGrid">
|
||
<code>400 invalid_parameter</code><p>请求结构或参数不受支持，检查字段类型、必填项及模型能力。</p>
|
||
<code>401 unauthorized</code><p>缺少、失效或无法识别的 API Key。</p>
|
||
<code>403 forbidden</code><p>API Key 权限范围不包含当前能力，或账号无权访问该模型。</p>
|
||
<code>404 not_found</code><p>任务、模型或其他目标资源不存在。</p>
|
||
<code>429 rate_limit</code><p>触发 RPM、TPM 或并发限制；按响应和运行策略退避重试。</p>
|
||
<code>5xx provider_failed</code><p>Gateway 或上游供应商暂时失败；结合 retryable、attempts 和 requestId 排查。</p>
|
||
</div>
|
||
</section>
|
||
<GuideSection title="异步任务失败">
|
||
<p>异步提交成功不代表生成成功。任务进入 <code>failed</code> 后，读取任务详情中的 <code>errorCode</code>、<code>errorMessage</code>、<code>requestId</code> 和 <code>attempts</code>。</p>
|
||
</GuideSection>
|
||
</>
|
||
);
|
||
}
|
||
|
||
return (
|
||
<>
|
||
<GuideSection title="启用请求级测试模式">
|
||
<p>在请求 Body 中同时设置 <code>runMode: simulation</code> 和 <code>simulation: true</code>。在线运行示例默认使用该配置。</p>
|
||
<pre>{`{\n "model": "gpt-4o-mini",\n "messages": [{ "role": "user", "content": "你好" }],\n "runMode": "simulation",\n "simulation": true\n}`}</pre>
|
||
</GuideSection>
|
||
<GuideSection title="测试模式的执行边界">
|
||
<p>测试任务仍会执行真实鉴权、模型路由、持久化队列、限流、进度事件和结果归一，因此可用于验证完整 Gateway 链路。</p>
|
||
<p>它不会向真实供应商提交任务、不会创建真实供应商订单，也不会产生真实扣费；任务、事件和结算结果会带有 <code>simulated=true</code> 标记。</p>
|
||
</GuideSection>
|
||
</>
|
||
);
|
||
}
|
||
|
||
function GuideSection(props: { children: ReactNode; title: string }) {
|
||
return (
|
||
<section className="paramCard docsDetailCard">
|
||
<header><h2>{props.title}</h2></header>
|
||
<div className="docsDetailContent">{props.children}</div>
|
||
</section>
|
||
);
|
||
}
|
||
|
||
function TaskResponseSchema() {
|
||
return (
|
||
<section className="paramCard">
|
||
<header>
|
||
<h2>响应 Body</h2>
|
||
<Badge variant="outline">application/json</Badge>
|
||
</header>
|
||
<ParamRows rows={taskResponseParamRows()} />
|
||
</section>
|
||
);
|
||
}
|
||
|
||
function DocDetails(props: { section: ApiDocSection }) {
|
||
if (props.section === 'responses') {
|
||
return (
|
||
<section className="paramCard docsDetailCard">
|
||
<header><h2>连续对话与状态归属</h2></header>
|
||
<div className="docsDetailContent">
|
||
<p>首次请求不传 <code>previous_response_id</code>。后续请求如需由 Responses 链续接，传入上一轮返回的 <code>response.id</code>。</p>
|
||
<p>未传 <code>previous_response_id</code> 时，网关以本轮完整 input 为准，不自动追加本地历史；客户端自行管理的完整上下文始终优先。</p>
|
||
<pre>{`{
|
||
"model": "gpt-4o-mini",
|
||
"input": "继续上一轮回答",
|
||
"previous_response_id": "resp_..."
|
||
}`}</pre>
|
||
</div>
|
||
</section>
|
||
);
|
||
}
|
||
if (props.section === 'videoGeneration') {
|
||
return (
|
||
<section className="paramCard docsDetailCard">
|
||
<header><h2>参考素材角色</h2></header>
|
||
<div className="docsDetailContent">
|
||
<p><code>image_url</code> 可使用 <code>first_frame</code>、<code>last_frame</code>、<code>reference_image</code>；<code>video_url</code> 和 <code>audio_url</code> 可作为视频、音频参考。实际数量和组合由所选模型能力约束。</p>
|
||
<p>视频生成通常耗时较长，生产调用建议设置 <code>X-Async: true</code>，再使用响应中的 <code>next.detail</code> 或任务取回接口查询结果。</p>
|
||
</div>
|
||
</section>
|
||
);
|
||
}
|
||
if (props.section === 'asyncMode') {
|
||
return (
|
||
<>
|
||
<section className="paramCard">
|
||
<header><h2>开启方式</h2></header>
|
||
<ParamRow name="X-Async" type="boolean" required value="在原请求 Header 中设置为 true；请求 URL、鉴权方式和 Body 均保持原接口定义不变。" />
|
||
</section>
|
||
<section className="paramCard docsDetailCard">
|
||
<header><h2>同步与异步的区别</h2></header>
|
||
<div className="docsStatusGrid">
|
||
<code>请求 Body</code><p>始终使用原接口的参数。异步模式没有独立的模型、提示词或媒体参数。</p>
|
||
<code>未设置 X-Async</code><p>连接等待任务执行，并按原接口协议返回同步 JSON 或 SSE 流。</p>
|
||
<code>X-Async: true</code><p>任务进入持久化队列，接口立即返回 HTTP 202；客户端通过 taskId 取回状态和最终结果。</p>
|
||
<code>适用范围</code><p>作为 AI 任务创建接口的统一能力使用，不与某一种文本、图片、视频或音频 Body 绑定。</p>
|
||
</div>
|
||
</section>
|
||
<section className="paramCard docsDetailCard">
|
||
<header><h2>异步受理响应</h2></header>
|
||
<div className="docsDetailContent">
|
||
<p>保存 <code>taskId</code>。<code>next.detail</code> 用于取回完整任务结果，<code>next.events</code> 用于订阅进度事件。</p>
|
||
<pre>{`HTTP/1.1 202 Accepted
|
||
{
|
||
"taskId": "9f4d8f3d-...",
|
||
"task": {
|
||
"id": "9f4d8f3d-...",
|
||
"status": "queued",
|
||
"asyncMode": true
|
||
},
|
||
"next": {
|
||
"detail": "/api/v1/tasks/9f4d8f3d-...",
|
||
"events": "/api/v1/tasks/9f4d8f3d-.../events"
|
||
}
|
||
}`}</pre>
|
||
</div>
|
||
</section>
|
||
</>
|
||
);
|
||
}
|
||
if (props.section === 'taskRetrieve') {
|
||
return (
|
||
<>
|
||
<section className="paramCard docsDetailCard">
|
||
<header><h2>状态与结果读取</h2></header>
|
||
<div className="docsStatusGrid">
|
||
<code>queued / submitting / running</code><p>任务仍在进行，保留 taskId 并继续查询；此时 <code>result</code> 通常为空。</p>
|
||
<code>succeeded</code><p>任务成功，原能力的归一化响应完整保存在 <code>result</code>；用量与结算分别位于 <code>usage</code>、<code>billings</code>。</p>
|
||
<code>failed</code><p>任务失败，读取 <code>errorCode</code>、<code>errorMessage</code>、<code>requestId</code> 和 <code>attempts</code>。</p>
|
||
<code>cancelled</code><p>任务已取消，不再继续执行；结合 <code>submitted</code> 判断是否曾提交到上游。</p>
|
||
</div>
|
||
</section>
|
||
<section className="paramCard docsDetailCard">
|
||
<header><h2>成功响应示例</h2></header>
|
||
<div className="docsDetailContent">
|
||
<p><code>result</code> 的内部字段与原始能力一致：文本、向量、重排序和媒体任务会保留各自的结果结构，外层任务字段保持统一。</p>
|
||
<pre>{`{
|
||
"id": "9f4d8f3d-...",
|
||
"kind": "images.generations",
|
||
"model": "image-model",
|
||
"asyncMode": true,
|
||
"status": "succeeded",
|
||
"result": {
|
||
"data": [{ "url": "https://example.com/result.png" }]
|
||
},
|
||
"usage": { "totalTokens": 0 },
|
||
"billings": [{
|
||
"resourceType": "image",
|
||
"unit": "image",
|
||
"quantity": 1,
|
||
"amount": 0.1,
|
||
"currency": "resource",
|
||
"simulated": false
|
||
}],
|
||
"billingSummary": {
|
||
"lineCount": 1,
|
||
"totalAmount": 0.1,
|
||
"currency": "resource",
|
||
"simulated": false
|
||
},
|
||
"finalChargeAmount": 0.1,
|
||
"attempts": [{
|
||
"attemptNo": 1,
|
||
"provider": "provider-name",
|
||
"status": "succeeded",
|
||
"retryable": false,
|
||
"responseDurationMs": 1280
|
||
}],
|
||
"createdAt": "2026-07-17T07:00:00Z",
|
||
"updatedAt": "2026-07-17T07:00:02Z",
|
||
"finishedAt": "2026-07-17T07:00:02Z"
|
||
}`}</pre>
|
||
</div>
|
||
</section>
|
||
</>
|
||
);
|
||
}
|
||
return null;
|
||
}
|
||
|
||
function authorizationDescription(section: ApiDocSection) {
|
||
const scope = section === 'embeddings'
|
||
? 'embedding'
|
||
: section === 'reranks'
|
||
? 'rerank'
|
||
: section === 'videoGeneration' || section === 'asyncMode'
|
||
? 'video'
|
||
: section === 'chat' || section === 'responses'
|
||
? 'chat'
|
||
: '';
|
||
return `Bearer {{YOUR_API_KEY}}，支持本地 API Key；管理接口仍使用 JWT。${scope ? `当前接口需要 ${scope} 权限。` : ''}`;
|
||
}
|
||
|
||
function supportsAsyncMode(section: ApiDocSection) {
|
||
return section === 'chat'
|
||
|| section === 'responses'
|
||
|| section === 'embeddings'
|
||
|| section === 'reranks'
|
||
|| section === 'imageGeneration'
|
||
|| section === 'imageEdit'
|
||
|| section === 'videoGeneration';
|
||
}
|
||
|
||
function MethodBadge(props: { method: NonNullable<ApiDocItem['method']> }) {
|
||
return <Badge variant={props.method === 'GET' ? 'success' : 'warning'}>{props.method}</Badge>;
|
||
}
|
||
|
||
function groupDocs(items: typeof apiDocs) {
|
||
const groups = new Map<string, typeof apiDocs>();
|
||
for (const item of items) {
|
||
groups.set(item.group, [...(groups.get(item.group) ?? []), item]);
|
||
}
|
||
return Array.from(groups, ([title, groupItems]) => ({ title, items: groupItems }));
|
||
}
|
||
|
||
function defaultTaskForDoc(kind: TaskForm['kind'], current: TaskForm, taskResult: GatewayTask | null): TaskForm {
|
||
const next = defaultTaskForKind(kind, current);
|
||
if (kind === 'tasks.retrieve' && !next.taskId && taskResult && !taskResult.id.startsWith('docs-')) {
|
||
return { ...next, taskId: taskResult.id };
|
||
}
|
||
return next;
|
||
}
|
||
|
||
function defaultTaskForKind(kind: TaskForm['kind'], current: TaskForm): TaskForm {
|
||
if (kind === 'chat.completions') return { ...current, kind, model: 'gpt-4o-mini' };
|
||
if (kind === 'responses') {
|
||
return {
|
||
...current,
|
||
instructions: current.instructions ?? '回答保持简洁。',
|
||
kind,
|
||
model: 'gpt-4o-mini',
|
||
prompt: current.kind === kind ? current.prompt : '用一句话说明 Responses API 的用途。',
|
||
};
|
||
}
|
||
if (kind === 'embeddings') {
|
||
return {
|
||
...current,
|
||
dimensions: current.dimensions ?? 4,
|
||
kind,
|
||
model: 'text-embedding-v4',
|
||
prompt: current.prompt || 'AI Gateway 提供 OpenAI 兼容接口。',
|
||
};
|
||
}
|
||
if (kind === 'reranks') {
|
||
return {
|
||
...current,
|
||
documents: current.documents ?? 'AI Gateway 提供 OpenAI 兼容接口。\n图片生成任务支持异步队列。\n文本向量接口返回 embedding 数组。',
|
||
kind,
|
||
model: 'qwen3-rerank',
|
||
prompt: current.prompt || 'OpenAI 兼容接口',
|
||
topN: current.topN ?? 2,
|
||
};
|
||
}
|
||
if (kind === 'images.edits') return { ...current, kind, image: current.image ?? 'https://example.com/source.png', mask: current.mask ?? 'https://example.com/mask.png', model: 'gpt-image-1' };
|
||
if (kind === 'images.generations') return { ...current, kind, model: 'gpt-image-1' };
|
||
if (kind === 'videos.generations') {
|
||
return {
|
||
...current,
|
||
aspectRatio: current.aspectRatio ?? '16:9',
|
||
duration: current.duration ?? 5,
|
||
kind,
|
||
model: '豆包Seedance-2.0',
|
||
outputAudio: current.outputAudio ?? true,
|
||
prompt: current.kind === kind ? current.prompt : '电影感航拍镜头掠过日出时的雪山。',
|
||
resolution: current.resolution ?? '720p',
|
||
};
|
||
}
|
||
return { ...current, kind, model: 'task' };
|
||
}
|
||
|
||
function requestBodyExample(task: TaskForm, section: ApiDocSection) {
|
||
const body = task.kind === 'chat.completions'
|
||
? { model: task.model, messages: [{ role: 'user', content: task.prompt }], runMode: 'simulation', simulation: true, stream: false }
|
||
: task.kind === 'responses'
|
||
? {
|
||
model: task.model,
|
||
input: task.prompt,
|
||
instructions: task.instructions,
|
||
previous_response_id: task.previousResponseId || undefined,
|
||
store: true,
|
||
stream: false,
|
||
runMode: 'simulation',
|
||
simulation: true,
|
||
}
|
||
: task.kind === 'embeddings'
|
||
? { model: task.model, input: embeddingInputExample(task.prompt), dimensions: task.dimensions ?? 4, runMode: 'simulation', simulation: true }
|
||
: task.kind === 'reranks'
|
||
? { model: task.model, query: task.prompt, documents: rerankDocumentsExample(task.documents), top_n: task.topN ?? 2, runMode: 'simulation', simulation: true }
|
||
: task.kind === 'images.edits'
|
||
? { model: task.model, prompt: task.prompt, image: task.image, mask: task.mask, runMode: 'simulation', simulation: true }
|
||
: task.kind === 'videos.generations'
|
||
? {
|
||
model: task.model,
|
||
content: [{ type: 'text', text: task.prompt }],
|
||
duration: task.duration ?? 5,
|
||
resolution: task.resolution ?? '720p',
|
||
aspect_ratio: task.aspectRatio ?? '16:9',
|
||
audio: task.outputAudio ?? true,
|
||
runMode: 'simulation',
|
||
simulation: true,
|
||
}
|
||
: section === 'pricing'
|
||
? { kind: 'chat.completions', model: 'gpt-4o-mini', messages: [{ role: 'user', content: '你好' }], max_tokens: 512 }
|
||
: { model: task.model, prompt: task.prompt, quality: 'medium', runMode: 'simulation', simulation: true, size: '1024x1024' };
|
||
return JSON.stringify(body, null, 2);
|
||
}
|
||
|
||
function parseBody(value: string, current: TaskForm): TaskForm {
|
||
try {
|
||
const body = JSON.parse(value) as {
|
||
image?: string;
|
||
aspect_ratio?: string;
|
||
audio?: boolean;
|
||
content?: Array<{ text?: string; type?: string }>;
|
||
duration?: number;
|
||
instructions?: string;
|
||
mask?: string;
|
||
messages?: Array<{ content?: string }>;
|
||
model?: string;
|
||
previous_response_id?: string;
|
||
prompt?: string;
|
||
input?: unknown;
|
||
query?: string;
|
||
documents?: string[];
|
||
resolution?: string;
|
||
top_n?: number;
|
||
dimensions?: number;
|
||
};
|
||
return {
|
||
...current,
|
||
aspectRatio: body.aspect_ratio ?? current.aspectRatio,
|
||
dimensions: numberOrCurrent(body.dimensions, current.dimensions),
|
||
documents: Array.isArray(body.documents) ? body.documents.join('\n') : current.documents,
|
||
duration: numberOrCurrent(body.duration, current.duration),
|
||
image: body.image ?? current.image,
|
||
instructions: body.instructions ?? current.instructions,
|
||
mask: body.mask ?? current.mask,
|
||
model: body.model ?? current.model,
|
||
outputAudio: typeof body.audio === 'boolean' ? body.audio : current.outputAudio,
|
||
previousResponseId: body.previous_response_id ?? current.previousResponseId,
|
||
prompt: body.prompt ?? body.query ?? inputText(body.input) ?? contentText(body.content) ?? body.messages?.[0]?.content ?? current.prompt,
|
||
resolution: body.resolution ?? current.resolution,
|
||
topN: numberOrCurrent(body.top_n, current.topN),
|
||
};
|
||
} catch {
|
||
return current;
|
||
}
|
||
}
|
||
|
||
function taskResponseParamRows(): ApiDocParam[] {
|
||
return [
|
||
{ name: 'id', type: 'string', required: true, value: 'Gateway 任务 ID，与异步受理响应中的 taskId 相同' },
|
||
{ name: 'kind', type: 'string', required: true, value: '原始任务类型，例如 chat.completions、images.generations 或 videos.generations' },
|
||
{ name: 'model', type: 'string', required: true, value: '请求使用的模型 ID 或别名' },
|
||
{ name: 'status', type: 'string', required: true, value: 'queued、submitting、running、succeeded、failed 或 cancelled' },
|
||
{ name: 'asyncMode', type: 'boolean', required: true, value: '是否以异步模式提交' },
|
||
{ name: 'cancellable', type: 'boolean', value: '当前状态是否允许取消' },
|
||
{ name: 'submitted', type: 'boolean', value: '任务是否已经提交到上游供应商' },
|
||
{ name: 'message', type: 'string', value: '当前状态或取消能力的补充说明' },
|
||
{ name: 'requestId', type: 'string', value: '上游请求 ID，用于日志和供应商问题定位' },
|
||
{ name: 'result', type: 'object', value: '任务成功后的归一化结果；内部结构与原始文本、向量、重排序、图片、视频或音频接口一致' },
|
||
{
|
||
name: 'usage',
|
||
type: 'object',
|
||
value: '归一化用量数据；媒体任务可能使用能力相关的用量字段',
|
||
children: [
|
||
{ name: 'inputTokens', type: 'number', value: '输入 token 数' },
|
||
{ name: 'outputTokens', type: 'number', value: '输出 token 数' },
|
||
{ name: 'totalTokens', type: 'number', value: '总 token 数' },
|
||
],
|
||
},
|
||
{
|
||
name: 'billings',
|
||
type: 'array<object>',
|
||
value: '逐项计费明细',
|
||
children: [
|
||
{ name: 'resourceType', type: 'string', required: true, value: '计费资源类型，例如 text_input、image 或 video' },
|
||
{ name: 'unit', type: 'string', required: true, value: '计费单位，例如 1k_tokens、image 或 5s_video' },
|
||
{ name: 'quantity', type: 'number', required: true, value: '计费数量' },
|
||
{ name: 'amount', type: 'number', required: true, value: '本计费项金额' },
|
||
{ name: 'currency', type: 'string', required: true, value: '金额单位，默认 resource' },
|
||
{ name: 'discountFactor', type: 'number', value: '实际应用的折扣系数' },
|
||
{ name: 'simulated', type: 'boolean', required: true, value: '是否为模拟计费' },
|
||
],
|
||
},
|
||
{
|
||
name: 'billingSummary',
|
||
type: 'object',
|
||
value: '计费汇总',
|
||
children: [
|
||
{ name: 'lineCount', type: 'number', required: true, value: '计费明细条数' },
|
||
{ name: 'totalAmount', type: 'number', required: true, value: '汇总金额' },
|
||
{ name: 'amountByCurrency', type: 'object', required: true, value: '按金额单位汇总的金额映射' },
|
||
{ name: 'currency', type: 'string', required: true, value: '单一金额单位或 mixed' },
|
||
{ name: 'simulated', type: 'boolean', required: true, value: '是否为模拟计费汇总' },
|
||
],
|
||
},
|
||
{ name: 'finalChargeAmount', type: 'number', required: true, value: '最终实际扣费金额；模拟任务不会真实扣费' },
|
||
{
|
||
name: 'attempts',
|
||
type: 'array<object>',
|
||
value: '执行尝试记录；发生重试或切换平台时可能包含多项',
|
||
children: [
|
||
{ name: 'attemptNo', type: 'number', required: true, value: '尝试序号，从 1 开始' },
|
||
{ name: 'provider', type: 'string', value: '供应商标识' },
|
||
{ name: 'modelName', type: 'string', value: 'Gateway 模型名称' },
|
||
{ name: 'providerModelName', type: 'string', value: '实际上游模型名称' },
|
||
{ name: 'status', type: 'string', required: true, value: '本次尝试状态' },
|
||
{ name: 'retryable', type: 'boolean', required: true, value: '失败后是否允许重试' },
|
||
{ name: 'simulated', type: 'boolean', required: true, value: '是否由 SimulationClient 执行' },
|
||
{ name: 'requestId', type: 'string', value: '本次尝试的上游请求 ID' },
|
||
{ name: 'responseDurationMs', type: 'number', required: true, value: '本次尝试的响应耗时（毫秒）' },
|
||
{ name: 'errorCode', type: 'string', value: '本次尝试失败时的错误码' },
|
||
{ name: 'errorMessage', type: 'string', value: '本次尝试失败时的错误信息' },
|
||
],
|
||
},
|
||
{ name: 'errorCode', type: 'string', value: '任务最终失败时的错误码' },
|
||
{ name: 'errorMessage', type: 'string', value: '任务最终失败时的错误信息' },
|
||
{ name: 'responseDurationMs', type: 'number', required: true, value: '任务响应耗时（毫秒）' },
|
||
{ name: 'createdAt', type: 'string', required: true, value: '任务创建时间，ISO 8601 格式' },
|
||
{ name: 'updatedAt', type: 'string', required: true, value: '任务最后更新时间，ISO 8601 格式' },
|
||
{ name: 'finishedAt', type: 'string', value: '任务进入终态的时间，ISO 8601 格式' },
|
||
];
|
||
}
|
||
|
||
function bodyParamRows(section: ApiDocSection): ApiDocParam[] {
|
||
if (section === 'responses') {
|
||
return [
|
||
{ name: 'model', type: 'string', required: true, value: '模型 ID 或别名；网关优先选择支持 openai_responses 的平台模型' },
|
||
{ name: 'input', type: 'string|array', required: true, value: '本轮输入，可为文本或 Responses input item 数组' },
|
||
{ name: 'instructions', type: 'string', value: '本轮系统级指令' },
|
||
{ name: 'previous_response_id', type: 'string', value: '上一轮 response.id；用于由客户端显式管理连续对话' },
|
||
{ name: 'store', type: 'boolean', value: '是否保存 Responses 链，默认 true' },
|
||
{ name: 'stream', type: 'boolean', value: '设为 true 时返回 Responses SSE 事件流' },
|
||
{ name: 'tools / tool_choice', type: 'array|object', value: '函数工具定义与选择策略；Chat 回退只支持 function tools' },
|
||
{ name: 'reasoning / text', type: 'object', value: '推理强度、文本格式和结构化输出配置' },
|
||
{ name: 'background', type: 'boolean', value: 'OpenAI 协议字段；Gateway 的持久化异步任务请使用 X-Async' },
|
||
];
|
||
}
|
||
if (section === 'embeddings') {
|
||
return [
|
||
{ name: 'model', type: 'string', required: true, value: '模型 ID 或别名，例如 text-embedding-v4' },
|
||
{ name: 'input', type: 'string|array', required: true, value: '需要向量化的文本或文本数组' },
|
||
{ name: 'dimensions', type: 'number', value: '可选向量维度，需模型支持' },
|
||
{ name: 'runMode / simulation', type: 'string|boolean', value: '在线测试时使用 simulation，不消耗真实上游额度' },
|
||
];
|
||
}
|
||
if (section === 'reranks') {
|
||
return [
|
||
{ name: 'model', type: 'string', required: true, value: '模型 ID 或别名，例如 qwen3-rerank' },
|
||
{ name: 'query', type: 'string', required: true, value: '用于相关性排序的查询文本' },
|
||
{ name: 'documents', type: 'array', required: true, value: '候选文档文本数组，至少 1 条' },
|
||
{ name: 'top_n', type: 'number', value: '返回前 N 条结果' },
|
||
{ name: 'runMode / simulation', type: 'string|boolean', value: '在线测试时使用 simulation，不消耗真实上游额度' },
|
||
];
|
||
}
|
||
if (section === 'videoGeneration') {
|
||
return [
|
||
{ name: 'model', type: 'string', required: true, value: '视频模型 ID 或别名，例如 豆包Seedance-2.0' },
|
||
{
|
||
name: 'content',
|
||
type: 'array<object>',
|
||
required: true,
|
||
value: '文本和参考素材对象数组；每一项由 type 决定应填写的内容字段和 role',
|
||
children: [
|
||
{ name: 'type', type: 'string', required: true, value: '内容类型：text、image_url、video_url、audio_url 或 element' },
|
||
{ name: 'text', type: 'string', value: 'type=text 时的提示词；配合 role=shot_prompt 可描述指定分镜' },
|
||
{
|
||
name: 'image_url',
|
||
type: 'object',
|
||
value: 'type=image_url 时的图片素材',
|
||
children: [
|
||
{ name: 'url', type: 'string', required: true, value: '可公开访问或已上传的图片 URL' },
|
||
],
|
||
},
|
||
{
|
||
name: 'video_url',
|
||
type: 'object',
|
||
value: 'type=video_url 时的视频素材及参考方式',
|
||
children: [
|
||
{ name: 'url', type: 'string', required: true, value: '可公开访问或已上传的视频 URL' },
|
||
{ name: 'mime_type', type: 'string', value: '视频 MIME 类型，例如 video/mp4' },
|
||
{ name: 'refer_type', type: 'string', value: '参考方式：feature（特征参考）或 base（基础视频）' },
|
||
{ name: 'keep_original_sound', type: 'string', value: '是否保留原声：yes 或 no' },
|
||
],
|
||
},
|
||
{
|
||
name: 'audio_url',
|
||
type: 'object',
|
||
value: 'type=audio_url 时的音频素材',
|
||
children: [
|
||
{ name: 'url', type: 'string', required: true, value: '可公开访问或已上传的音频 URL' },
|
||
{ name: 'mime_type', type: 'string', value: '音频 MIME 类型，例如 audio/mpeg' },
|
||
],
|
||
},
|
||
{ name: 'role', type: 'string', value: '素材角色，例如 first_frame、last_frame、reference_image、reference_video、reference_audio、element 或 shot_prompt' },
|
||
{ name: 'shot_index', type: 'number', value: '素材或提示词对应的分镜序号' },
|
||
{ name: 'duration', type: 'number', value: '当前分镜或素材的时长（秒）' },
|
||
{ name: 'name', type: 'string', value: '素材或元素名称' },
|
||
{
|
||
name: 'element',
|
||
type: 'object',
|
||
value: 'type=element 时使用的系统元素或内联元素',
|
||
children: [
|
||
{ name: 'system_element_id', type: 'string', value: '已存在的系统元素 ID' },
|
||
{
|
||
name: 'inline_element',
|
||
type: 'object',
|
||
value: '随请求提交的内联元素定义',
|
||
children: [
|
||
{ name: 'name', type: 'string', required: true, value: '内联元素名称' },
|
||
{ name: 'description', type: 'string', value: '内联元素描述' },
|
||
{ name: 'frontal_image_url', type: 'string', required: true, value: '元素正面参考图 URL' },
|
||
{
|
||
name: 'refer_images',
|
||
type: 'array<object>',
|
||
required: true,
|
||
value: '元素的补充参考图片对象数组',
|
||
children: [
|
||
{ name: 'url', type: 'string', required: true, value: '参考图片 URL' },
|
||
{ name: 'slot_key', type: 'string', value: '参考图槽位标识' },
|
||
],
|
||
},
|
||
{ name: 'tags', type: 'array<string>', value: '元素标签数组' },
|
||
],
|
||
},
|
||
],
|
||
},
|
||
],
|
||
},
|
||
{ name: 'duration', type: 'number', value: '视频时长（秒），允许范围取决于模型能力' },
|
||
{ name: 'resolution', type: 'string', value: '输出分辨率，例如 480p、720p、1080p' },
|
||
{ name: 'aspect_ratio', type: 'string', value: '画幅，例如 16:9、9:16、1:1 或 adaptive' },
|
||
{ name: 'audio', type: 'boolean', value: '是否生成或保留声音，需模型支持 output_audio' },
|
||
{
|
||
name: 'audio_list',
|
||
type: 'array<object>',
|
||
value: '额外音频素材对象数组',
|
||
children: [
|
||
{ name: 'url', type: 'string', value: '音频 URL' },
|
||
{ name: 'audio_url', type: 'string', value: '音频 URL 的兼容字段' },
|
||
{ name: 'name', type: 'string', value: '音频名称' },
|
||
],
|
||
},
|
||
{ name: 'prompt', type: 'string', value: '纯文生视频的快捷字段；网关会转换为 content 文本项' },
|
||
{ name: 'runMode / simulation', type: 'string|boolean', value: '在线测试时使用 simulation，不触达真实视频供应商' },
|
||
];
|
||
}
|
||
if (section === 'pricing') {
|
||
return [
|
||
{ name: 'kind', type: 'string', value: '任务类型，默认 chat.completions' },
|
||
{ name: 'model', type: 'string', required: true, value: '需要估价的模型 ID 或别名' },
|
||
{ name: 'messages / prompt', type: 'array|string', value: '用于估算输入规模的请求内容' },
|
||
{ name: 'max_tokens / n', type: 'number', value: '预期输出 token 或媒体数量' },
|
||
];
|
||
}
|
||
if (section === 'chat') {
|
||
return [
|
||
{ name: 'model', type: 'string', required: true, value: '模型 ID 或别名' },
|
||
{ name: 'messages', type: 'array', required: true, value: 'OpenAI Chat 消息数组' },
|
||
{ name: 'stream', type: 'boolean', value: '设为 true 时返回 Chat Completions SSE' },
|
||
{ name: 'tools / tool_choice', type: 'array|object', value: '函数工具定义与选择策略' },
|
||
{ name: 'simulation', type: 'boolean', value: '测试模式开关' },
|
||
];
|
||
}
|
||
return [
|
||
{ name: 'model', type: 'string', required: true, value: '模型 ID 或别名' },
|
||
{ name: 'prompt', type: 'string', required: true, value: '图片生成或编辑提示词' },
|
||
{ name: 'image / mask', type: 'string|array', value: '图像编辑输入与可选遮罩' },
|
||
{ name: 'simulation', type: 'boolean', value: '测试模式开关' },
|
||
];
|
||
}
|
||
|
||
function docSectionForKind(kind: TaskKind): ApiDocSection {
|
||
if (kind === 'responses') return 'responses';
|
||
if (kind === 'embeddings') return 'embeddings';
|
||
if (kind === 'reranks') return 'reranks';
|
||
if (kind === 'images.generations') return 'imageGeneration';
|
||
if (kind === 'images.edits') return 'imageEdit';
|
||
if (kind === 'videos.generations') return 'videoGeneration';
|
||
if (kind === 'tasks.retrieve') return 'taskRetrieve';
|
||
return 'chat';
|
||
}
|
||
|
||
function embeddingInputExample(prompt: string) {
|
||
const lines = splitLines(prompt);
|
||
return lines.length > 1 ? lines : (lines[0] ?? prompt);
|
||
}
|
||
|
||
function rerankDocumentsExample(value?: string) {
|
||
return splitLines(value ?? '').length
|
||
? splitLines(value ?? '')
|
||
: ['AI Gateway 提供 OpenAI 兼容接口。', '图片生成任务支持异步队列。'];
|
||
}
|
||
|
||
function splitLines(value: string) {
|
||
return value
|
||
.split(/\n+/)
|
||
.map((item) => item.trim())
|
||
.filter(Boolean);
|
||
}
|
||
|
||
function inputText(value: unknown) {
|
||
if (typeof value === 'string') return value;
|
||
if (Array.isArray(value)) {
|
||
const texts = value.map((item) => typeof item === 'string' ? item : '').filter(Boolean);
|
||
return texts.length ? texts.join('\n') : undefined;
|
||
}
|
||
return undefined;
|
||
}
|
||
|
||
function contentText(value?: Array<{ text?: string; type?: string }>) {
|
||
return value?.find((item) => item.type === 'text' && item.text)?.text;
|
||
}
|
||
|
||
function numberOrCurrent(value: unknown, current?: number) {
|
||
return typeof value === 'number' && Number.isFinite(value) ? value : current;
|
||
}
|