yino.ai 媒体 API

如何调用

使用你手头任意的 HTTP 工具即可 —— 例如 curl、Python requests、Node fetch，或语言内置的 HTTP 客户端。
这些 API 面向 agent 设计：错误响应中包含清晰的解释和文档链接；批量模式（batch mode）可显著减少网络往返次数。

预检

1. echo $YINO_API_KEY —— 必须已设置。你可在 https://yino.ai/settings（API Keys 区域）获取密钥。
2. echo ${YINO_API_BASE_URL:-https://yino.ai} —— 默认指向生产环境。本地开发时，请设置 YINO_API_BASE_URL=http://localhost:3000。

若任一检查失败，请立即中止并告知用户。

认证

每个请求均需携带：Authorization: Bearer $YINO_API_KEY

第一步：发现能力（Discover Capabilities）

务必从此步开始。 不要假设模型名称或参数 —— 务必动态发现：

curl "${YINO_API_BASE_URL:-https://yino.ai}/api/agent/capabilities" 
  -H "Authorization: Bearer $YINO_API_KEY"

该接口返回所有可用模型与工具，包括其 endpoint、标签（tags）及文档链接（doc links）。模型会随时间演进 —— 务必始终优先执行能力发现。

每项能力均包含一个 doc 字段（例如 /docs/models/seedream-4-5.mdx）。在调用任一 endpoint 前，请先获取该文档以了解所需输入参数：

curl "${YINO_API_BASE_URL:-https://yino.ai}{doc_field_value}"

文档 URL 规约： 所有以 .mdx 结尾的 URL 均返回原始 Markdown 内容 —— 即网站上用户所见的相同文档，但可直接由你程序化读取。每篇文档开头均含面包屑导航（例如 > [docs](/docs) / [models](/docs/models) / seedream-4-5），其中链接可点击跳转至父级页面或同级文档。

第二步：关键模式（Key Patterns）

项目（Projects）： 项目用于归组相关生成任务，并支持可视化预览页面。以下两种场景建议使用项目：

1. 前置创建（Upfront） —— 当用户任务明确涉及多个关联生成（如分镜脚本、风格探索、多镜头视频）时，可建议：“是否需要我为您创建一个项目，以便您集中预览全部结果？”
2. 回溯创建（Retroactive） —— 当你已生成若干关联内容但未创建项目时，可建议：“我已生成若干相关素材，是否需要我将它们归入一个项目统一管理？” 然后创建项目，并通过 PATCH /api/agent/generations/:id 配合 project_id 将已有生成项分配至该项目。

项目创建完成后，请立即向用户分享项目链接：${YINO_API_BASE_URL}/projects/{project_id} —— 用户可打开该链接实时查看生成进度，并浏览已产出的结果。

请阅读 references/project-preview.md 了解项目工作流、预览区块类型、增量更新策略及具体示例。

异步 + 轮询（Async + Polling）： 模型 endpoint 返回的是 task_id（或多个 ID），而非最终结果。请使用 sleep 加指数退避（exponential backoff）进行轮询，以平衡“轮询过频”与“等待过久”的矛盾。

curl "${YINO_API_BASE_URL}/api/agent/generations/status?ids=id1,id2" 
  -H "Authorization: Bearer $YINO_API_KEY"

每项生成任务具有 status（状态流转：pending → processing → done / failed），完成时提供 output.url。

轮询建议：

• 手动逐次轮询。两次轮询之间使用 sleep 并配合指数退避 —— 切勿编写自动循环脚本，此类脚本会阻塞你的执行环境，妨碍你在等待期间执行其他有用任务。
• 等待期间请主动推进其他工作：若存在多个待处理批次，可轮询另一批次；对已就绪的结果，可更新项目预览；也可向用户同步当前进展。
• 每次轮询间隙，均应向用户说明当前状态。

批量模式（Batch mode）： 当需处理多个项目时，务必启用批量模式。一次请求提交 10 个条目，远优于发起 10 次独立请求。请将输入数据包裹于 {"items": [...]} 中（最多支持 20 项）。

文件上传（File upload）： 当需提供文件（图像、音频）时，请先上传：

curl -X POST "${YINO_API_BASE_URL}/api/agent/upload" 
  -H "Authorization: Bearer $YINO_API_KEY" 
  -F "file=@path/to/file"

接口返回一个可被其他 endpoint 引用的 URL。单文件上限 10MB，支持图像与音频格式。

错误处理

所有错误响应均面向 agent 友好设计。每个错误响应均包含：

• error —— 人类可读的错误信息，说明问题原因
• doc —— 指向相关文档的链接

当遇到错误时，请立即获取 doc 链接查阅详细指导。大多数问题仅凭错误消息本身即可自主诊断。

缓存

若用户重复执行同类任务达 3–4 次，可询问是否希望你将常用参数保存为其 workspace 中的一条备注。未经用户明确许可，不得擅自保存任何内容。