用途:帮助开发者在由 IMG.LY 托管(部署在 IMG.LY 产品界面、使用 IMG.LY 的 Clerk 终端用户认证)的应用中,从客户端直接调用 IMG.LY AI Gateway。仅适用于该特定场景;若开发者自带 API key、在 IMG.LY 托管环境之外构建,或自建后端签发 gateway JWT,应改用 gateway-client 技能。
认证方式:用户会话由 Clerk 签发的 JWT 表示,网关接受该 JWT 并将生成费用计入用户的 IMG.LY 账户。客户端直接发送:Authorization: Bearer <clerk-session-jwt>。没有 token 签发跳转,没有 POST /v1/tokens,客户端不放置 API key。
代码接入:使用 Clerk SDK 的 useAuth() 获取 getToken,在每次请求时取 Clerk 会话 JWT 并设置 Authorization 与 Content-Type 头,再请求 https://gateway.img.ly 对应路径。服务端渲染或 server actions 场景,从 Clerk 服务端 SDK 获取 token(如 Next.js 的 auth().getToken())并转发到网关请求。
与标准集成相同之处:端点、请求结构、SSE 事件名、错误码、schema 驱动输入、模型发现、资源上传流程均一致。这些内容以 https://gateway.img.ly/llms.txt 为准,回答生成、模型、schema、上传等具体问题前应先读取该文档;该文档不涵盖此处描述的 Clerk JWT 认证路径。
注意事项:Clerk 会话 JWT 有效期短,getToken() 按请求调用会自动刷新,不要跨长时间操作缓存。用户权限范围由 IMG.LY 管理,客户端无法扩大;若返回 provider_not_authorized,表示该账户无权调用该模型,应给出明确错误而非重试。额度计入用户关联的 IMG.LY 账户,insufficient_credits(402)属账户级状态,应引导用户到 IMG.LY 控制台充值。不要在此类应用中放置 IMG.LY API key(sk_...)。CORS、cookie 与来源限制按 IMG.LY 托管环境配置,若应用从其他位置提供服务,此认证路径可能不可用,需回退到标准集成。
不涵盖:Clerk 应用开通、IMG.LY 托管配置与域名部署等平台事务;标准公开集成路径(API key、gateway JWT 签发);网关内部架构与运维。