# API

> Connect to AI models through your API gateway.

## 开始使用

- [项目介绍](https://docs.playapi.ai/zh/introduction.md): 通过一个 API 网关接入不同的 AI 模型。
- [快速开始](https://docs.playapi.ai/zh/quickstart.md): 准备服务地址和 API Key，查询模型并发起第一次对话请求。
- [示例索引与学习路径](https://docs.playapi.ai/zh/guides/recipes.md): 按接入目标找到 API、完整脚本和验证边界。

## 接入指南

- [地址、密钥与模型](https://docs.playapi.ai/zh/guides/api-basics.md): 把客户端连接到正确的部署，并确认模型能力。
- [选择协议与模型能力](https://docs.playapi.ai/zh/guides/model-capabilities.md): 从任务选择接口，区分模型可见、接口可用与功能支持。
- [模型路由与故障切换](https://docs.playapi.ai/zh/guides/model-routing.md): 区分模型 ID、供应商选择、渠道重试与应用层回退。
- [接口支持范围](https://docs.playapi.ai/zh/guides/api-coverage.md): 区分已提供的接口、部署相关能力与未实现功能。
- [HTTP 与 cURL](https://docs.playapi.ai/zh/guides/http.md): 直接发送 JSON 请求并读取返回结果。
- [Python SDK](https://docs.playapi.ai/zh/guides/python.md): 配置兼容地址，调用 Chat Completions 和 Responses。
- [TypeScript SDK](https://docs.playapi.ai/zh/guides/typescript.md): 配置兼容地址，调用 Chat Completions 和 Responses。
- [Vercel AI SDK 接入](https://docs.playapi.ai/zh/guides/ai-sdk.md): 使用 OpenAI Compatible Provider，通过服务端 Chat Completions 接入。
- [Claude 原生协议](https://docs.playapi.ai/zh/guides/native-claude.md): 通过网关调用 Messages，检查内容块与结束原因。
- [Claude 原生 SSE 与工具闭环](https://docs.playapi.ai/zh/guides/native-claude-streaming.md): 接收原生事件、验证完整调用、保留推理状态并回传工具结果。
- [Gemini 原生协议](https://docs.playapi.ai/zh/guides/native-gemini.md): 使用模型路径、原生 contents 和 candidates 调用 Gemini。
- [Gemini 内置工具](https://docs.playapi.ai/zh/guides/gemini-builtins.md): 使用三模式可运行示例接入原生搜索引用、URL 上下文与上游代码执行。
- [Gemini 原生 SSE 与工具闭环](https://docs.playapi.ai/zh/guides/native-gemini-streaming.md): 接收原生事件、验证完整调用、保留推理状态并回传工具结果。
- [流式输出](https://docs.playapi.ai/zh/guides/streaming.md): 分别处理 Chat Completions 与 Responses 的 SSE 事件。
- [错误与重试](https://docs.playapi.ai/zh/guides/errors.md): 按状态、错误体和请求日志定位问题。
- [SDK 与框架迁移清单](https://docs.playapi.ai/zh/guides/sdk-migration.md): 从官方服务或其他网关迁移已有应用。
- [WebSocket 连接与运行环境](https://docs.playapi.ai/zh/guides/websocket.md): 配置服务端客户端、连接限制与共享传输模块。
- [Responses WebSocket 接入](https://docs.playapi.ai/zh/guides/responses-websocket.md): 在一个连接中完成两轮对话，校验完整结果并回放历史。
- [Realtime 文字与语音接入](https://docs.playapi.ai/zh/guides/realtime.md): 配置 GA 会话，发送文字或 PCM 音频并保存完成的音频响应。

## 应用实践

- [多轮对话](https://docs.playapi.ai/zh/guides/conversations.md): 维护消息历史，让后续问题引用前文。
- [上下文管理](https://docs.playapi.ai/zh/guides/context-management.md): 在显式历史、状态引用、压缩和应用裁剪之间选择合适方案。
- [提示词缓存](https://docs.playapi.ai/zh/guides/prompt-caching.md): 区分上游前缀缓存、渠道亲和与响应缓存，检查实际缓存用量。
- [推理模型接入](https://docs.playapi.ai/zh/guides/reasoning-models.md): 选择协议对应的推理参数，验证最终输出并保留可续用状态。
- [工具调用](https://docs.playapi.ai/zh/guides/tool-calling.md): 接收函数调用、执行本地逻辑，再把结果交还模型。
- [工具选择与并行控制](https://docs.playapi.ai/zh/guides/tool-controls.md): 使用 tool_choice 和 parallel_tool_calls 控制工具轮次，核实 strict 的转换限制。
- [联网搜索与引用](https://docs.playapi.ai/zh/guides/web-search.md): 使用原生 Responses 搜索工具，保留引用并检查渠道支持边界。
- [流式工具调用](https://docs.playapi.ai/zh/guides/streaming-tools.md): 组装交错参数分片，验证完成后执行并关联工具结果。
- [结构化输出](https://docs.playapi.ai/zh/guides/structured-output.md): 按指定结构读取 JSON，并处理拒答、截断与校验失败。
- [JSON 模式与结果校验](https://docs.playapi.ai/zh/guides/json-mode.md): 运行 Chat 与 Responses 的 json_object 示例，区分合法 JSON、字段约束和业务正确性。
- [生成参数与 Logprobs](https://docs.playapi.ai/zh/guides/generation-parameters.md): 了解采样、重复惩罚、seed 和 token 概率的模型及渠道限制。
- [预测输出](https://docs.playapi.ai/zh/guides/predicted-outputs.md): 为已知大部分内容的文本修改提供 prediction，明确渠道与转换限制。
- [图片理解](https://docs.playapi.ai/zh/guides/vision.md): 把图片作为对话输入，获取文字描述。
- [PDF 与文件输入](https://docs.playapi.ai/zh/guides/file-inputs.md): 通过原生 Responses 发送内联 PDF，明确文件存储和解析边界。
- [Responses 上下文压缩](https://docs.playapi.ai/zh/guides/compaction.md): 压缩完整历史，保留返回窗口后继续对话。
- [后台响应与任务查询](https://docs.playapi.ai/zh/guides/background-responses.md): 查询插件任务响应，区分后台执行与普通上游响应。
- [内容审核](https://docs.playapi.ai/zh/guides/moderations.md): 检查文本审核结果，并处理失败与人工复核。

## 多模态接入

- [图片生成与编辑](https://docs.playapi.ai/zh/guides/image-generation.md): 生成、编辑、解码与保存图片结果。
- [语音合成](https://docs.playapi.ai/zh/guides/speech.md): 将文本转换为音频，并正确保存二进制响应。
- [语音转写与翻译](https://docs.playapi.ai/zh/guides/speech-to-text.md): 上传音频、读取文本，并区分转写与翻译。
- [音频对话输入](https://docs.playapi.ai/zh/guides/audio-input.md): 通过 Chat 内容块发送录音并获取文本，区分转写、语音生成与实时会话。
- [视频生成与任务管理](https://docs.playapi.ai/zh/guides/video-generation.md): 创建、查询、下载及重混视频任务。
- [视频理解](https://docs.playapi.ai/zh/guides/video-understanding.md): 通过 Gemini 原生内容输入分析视频，说明 Chat 视频扩展及文件上传边界。

## 检索与重排

- [Embeddings 向量检索](https://docs.playapi.ai/zh/guides/embeddings.md): 生成文本向量，正确匹配输入并实现小规模检索。
- [Rerank 文档重排](https://docs.playapi.ai/zh/guides/rerank.md): 重排候选文档，正确关联索引、原文与相关性分数。
- [RAG 知识库问答](https://docs.playapi.ai/zh/guides/rag.md): 串联向量召回、可选重排与带来源回答，验证每一步结果。

## 生产与排障

- [生产接入检查](https://docs.playapi.ai/zh/guides/production.md): 明确超时、并发、日志和真实服务验收标准。
- [数据控制与参数过滤](https://docs.playapi.ai/zh/guides/data-controls.md): 区分请求字段、渠道过滤、上游存储以及部署日志策略。
- [限流与有界重试](https://docs.playapi.ai/zh/guides/rate-limits.md): 识别 429、Retry-After 与多层重试，运行只读诊断示例。
- [请求观测与排障记录](https://docs.playapi.ai/zh/guides/observability.md): 关联应用与网关请求，区分响应头延迟、首事件时间和完成状态。
- [接入排障与常见问题](https://docs.playapi.ai/zh/guides/troubleshooting.md): 按症状定位地址、协议、状态和结果处理问题。

## 补充协议与任务

- [REST 示例运行环境](https://docs.playapi.ai/zh/guides/http-runtime.md): 配置根地址与共享 HTTP 模块，执行新增 REST 示例。
- [旧版文本补全](https://docs.playapi.ai/zh/guides/legacy-completions.md): 使用 prompt 完成旧版同步与流式文本补全。
- [Gemini 原生向量](https://docs.playapi.ai/zh/guides/gemini-embeddings.md): 调用原生单条与同步批量向量，验证数量和维度。
- [通用任务与产物下载](https://docs.playapi.ai/zh/guides/tasks.md): 区分任务受理与完成，查询状态并下载产物。
- [Alpha Search 专用接入](https://docs.playapi.ai/zh/guides/alpha-search.md): 核对专用上游请求格式与透传响应的边界。
- [Midjourney 任务接入](https://docs.playapi.ai/zh/guides/midjourney.md): 查询已有任务，理解动作路由和业务错误。
- [兼容入口与插件边界](https://docs.playapi.ai/zh/guides/protocol-compatibility.md): 核对历史入口、动态插件路由和文档覆盖范围。

## API 参考

- [API 概览](https://docs.playapi.ai/zh/api-reference/overview.md): 核心推理接口、协议范围与可迁移规范。
- [列出模型](https://docs.playapi.ai/zh/api-reference/models.md): 获取当前调用凭据可见的模型 ID。
- [查询单个模型](https://docs.playapi.ai/zh/api-reference/model-retrieve.md): 查询模型元数据并识别 HTTP 200 中的错误。
- [创建对话](https://docs.playapi.ai/zh/api-reference/chat-completions.md): 发送消息历史，获取完整回复或流式增量。
- [创建响应](https://docs.playapi.ai/zh/api-reference/responses.md): 使用 Responses 结构发起模型调用。
- [压缩响应上下文](https://docs.playapi.ai/zh/api-reference/responses-compact.md): 返回可用于下一轮 Responses 请求的完整窗口。
- [查询插件任务响应](https://docs.playapi.ai/zh/api-reference/responses-retrieve.md): 读取本平台插件任务的 Responses 状态与输出。
- [Claude Messages](https://docs.playapi.ai/zh/api-reference/claude-messages.md): 创建 Claude 原生消息，保留内容块与结束原因。
- [Gemini generateContent](https://docs.playapi.ai/zh/api-reference/gemini-generate.md): 通过模型路径创建 Gemini 原生内容。
- [Gemini streamGenerateContent](https://docs.playapi.ai/zh/api-reference/gemini-stream.md): 原生 SSE 文本与函数工具调用。
- [生成图片](https://docs.playapi.ai/zh/api-reference/images-generations.md): 请求格式、响应与能力边界。
- [编辑图片](https://docs.playapi.ai/zh/api-reference/images-edits.md): 请求格式、响应与能力边界。
- [合成语音](https://docs.playapi.ai/zh/api-reference/audio-speech.md): 请求格式、响应与能力边界。
- [转写音频](https://docs.playapi.ai/zh/api-reference/audio-transcriptions.md): 请求格式、响应与能力边界。
- [翻译音频](https://docs.playapi.ai/zh/api-reference/audio-translations.md): 请求格式、响应与能力边界。
- [创建视频任务](https://docs.playapi.ai/zh/api-reference/videos-create.md): 请求格式、响应与能力边界。
- [查询视频任务](https://docs.playapi.ai/zh/api-reference/videos-retrieve.md): 请求格式、响应与能力边界。
- [下载视频](https://docs.playapi.ai/zh/api-reference/videos-content.md): 请求格式、响应与能力边界。
- [检查视频内容](https://docs.playapi.ai/zh/api-reference/videos-content-head.md): 请求格式、响应与能力边界。
- [重混视频](https://docs.playapi.ai/zh/api-reference/videos-remix.md): 请求格式、响应与能力边界。
- [生成向量](https://docs.playapi.ai/zh/api-reference/embeddings.md): 请求参数、响应与渠道兼容边界。
- [重排文档](https://docs.playapi.ai/zh/api-reference/rerank.md): 请求参数、响应与渠道兼容边界。
- [创建内容审核](https://docs.playapi.ai/zh/api-reference/moderations.md): 审核单条文本或文本数组。
- [Responses WebSocket API](https://docs.playapi.ai/zh/api-reference/responses-websocket.md): 握手、create 字段、事件关联和当前网关限制。
- [Realtime WebSocket API](https://docs.playapi.ai/zh/api-reference/realtime.md): GA 会话配置、文字音频事件与终态判断。
- [创建文本补全](https://docs.playapi.ai/zh/api-reference/completions.md): prompt 请求、text 输出及 SSE 完成字段。
- [Gemini 单条向量](https://docs.playapi.ai/zh/api-reference/gemini-embed.md): 原生 content.parts 输入与 embedding.values 输出。
- [Gemini 同步批量向量](https://docs.playapi.ai/zh/api-reference/gemini-batch-embed.md): 同步批量向量结构与当前模型别名限制。
- [提交通用插件任务](https://docs.playapi.ai/zh/api-reference/tasks-submit.md): 通过旧通用入口提交插件规范化 JSON 请求。
- [查询通用任务](https://docs.playapi.ai/zh/api-reference/tasks-retrieve.md): 读取持久化任务状态、进度及时间戳。
- [列出任务产物](https://docs.playapi.ai/zh/api-reference/task-artifacts.md): 读取产物 key、类型、MIME 与内容地址。
- [下载任务产物](https://docs.playapi.ai/zh/api-reference/task-artifact-content.md): 下载完整或部分二进制产物，处理未就绪状态。
- [检查任务产物](https://docs.playapi.ai/zh/api-reference/task-artifact-head.md): 检查产物响应头与条件请求行为。
- [Alpha Search 专用请求](https://docs.playapi.ai/zh/api-reference/alpha-search.md): 宿主 model 字段与上游自定义搜索契约。
- [查询 Midjourney 任务](https://docs.playapi.ai/zh/api-reference/midjourney-task.md): 按公开任务 ID 读取状态并识别业务错误。

## OpenAPI Specs

- [relay](/openapi/relay.json)

> The links below point to documentation indexes. Follow each `/_llms/` index recursively until you reach documentation pages.

## Indexes

- [English (95 pages)](https://docs.playapi.ai/_llms/en.txt): Documentation for English.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.