# qwen-service

chat.qwen.ai 的**双门出口**：视频门（火山方舟 Seedance 契约，t2v/i2v）+ chat 门（OpenAI 形态，t2t 文本 + 图片/文件/音频/视频解析）。多账号池 + 完整指纹请求头 + 轻量排队重试。给 OpenAI 兼容客户端 / 网关使用——Base URL 指向本服务、Key 换成本服务的即可。

最小可用（chat 门）：

```bash
curl -s $BASE/v1/chat/completions -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"model":"qwen3.7-plus","messages":[{"role":"user","content":"你好"}]}'
```

## ⚠️ 先读（额度与边界）

- 🔴 **视频额度 3 次/天/账号**（UTC 日，t2v+i2v 共用）——视频生成是计费动作，队列重试只覆盖"可证明未提交"的失败；**对话与解析不消耗视频额度**。
- 🔴 **对话上下文实测 ≈5 万汉字内可靠**（上游自报 1M tokens，但 WAF 在 ~6 万字触发风控，换出口不可绕过）——超长请分段或摘要。
- **视频时长固定 ~5s**（duration 参数只接受 5，其余吸附/拒绝）；`ratio` 只吃 1:1/3:4/4:3/16:9/9:16，枚举外落 1:1。
- **一次 1 个附件**（图片/文件/音频/视频），≤20MB，http(s) URL 或 data: URI；多轮对话请把附件放在**最后一条** user 消息。
- 上游风控 429（`ServerOverloaded`）**勿连打**——重试会加深标记。

## 能力

| model | 通路 | 必填输入 | 附件 | 说明 |
|---|---|---|---|---|
| `qwen/video` | 视频生成（异步任务） | text prompt；图片可选（单张首帧） | 不支持附件混合 | 时长固定 ~5s；产物 URL 7 天内可取 |
| `qwen3.7-plus`、`qwen3.8-max` | 对话 / 多模态解析（同步） | messages（最后一条 user 可带 1 个附件） | 图片(直链/data:)/文件/音频/视频 | 流式与非流式均支持 |

已注册 2 个上游 chat 模型（TTL 缓存，来自上游 `GET /api/models`，仅注册真正可跑 t2t 的条目）。
思考档位：`reasoning_effort`（`none`/`minimal`=快速、`high`=强制思考、缺省=自动）或 `enable_thinking:false`；流式思考期发空格心跳变相加速首字（正文前导一个空格）。
注意：少数模型（如 `qwen3.8-omni-flash`）在自动/强制思考档会把思考过程并入正文 `content`（无 `reasoning_content` 字段）——本服务对这类模型**缺省自动切快速档**保证正文干净；显式传 `reasoning_effort:"high"` 则照发（风险只记服务端日志）。

### 附件解析（chat 门）

| 分段类型 | 来源形态 | 处理 |
|---|---|---|
| `image_url` | http(s) 直链 | 直接引用（上游域内图已实测；外链照发+告警） |
| `image_url` | data: URI | 服务端转上传链 |
| `file` / `input_file` | http(s) URL | 服务端代下载 → 上传 → 文档解析 |
| `input_audio` / `audio_url` | base64 / URL | 服务端转上传链 → 音频理解 |
| `video_url` | URL / data: URI | 服务端转上传链 → 视频理解 |
| 多个附件 | — | **400**（一次一个，不替你挑） |

## 端点

| 端点 | 鉴权 | 说明 |
|---|---|---|
| `GET /llms.txt` | 免 | 本文件 |
| `GET /` | 免 | HTML 落地页 |
| `GET /v1/models` | 免 | 能力清单（OpenAI 形态） |
| `POST /v1/chat/completions` | **Key** | 对话/解析（t2t；`tools` 等见回退节） |
| `POST /v1/responses` | **Key** | Responses 形态（语义同上） |
| `POST /api/v3/contents/generations/tasks` | **Key** | 视频·创建（方舟契约，只回 id） |
| `GET /api/v3/contents/generations/tasks/{id}` | 允许无 Key | 视频·查询（id 即凭据） |
| `GET /healthz` `/readyz` | 免 | 探活（`/stats` 建议反代层封禁） |

鉴权：`Authorization: Bearer <凭据>`，两种形态 —— ① `邮箱|口令` 账号串（**形状合规即收**，不查白名单）；② qwen access token（不验签）。均不校验真实性。

## 回退通道

**已启用**：对话门遇到 qwen 做不了的能力（`tools` 函数调用、文件/音频/视频附件、多图、data: 图片）时，**整单转方舟 chat/responses 原生执行**——函数调用与内置搜索真实生效。应答 `model` 字段回显请求值、带 `x-qwen-fallback: ark` 头；回退模型名全链路脱敏（含报错报文）。回退通道故障 ⇒ 502，不静默降回。

## 附件上传链

上传链：**已启用**：附件由服务端代下载（SSRF 防护）→ 上传上游 OSS → 原生解析。单附件 ≤20MB（`QWEN_UPLOAD_MAX_BYTES`）。

## 错误

视频门 `type` 为方舟词汇；chat 门按 HTTP 映射 OpenAI 词汇（400 `invalid_request_error`、401 `authentication_error`、429 `rate_limit_error`、5xx `server_error`）。所有响应带 `x-request-id`。

| HTTP | code | retryable | 何时 |
|---|---|---|---|
| 400 | `InvalidParameter` | ❌ 勿自动重试 | 请求本身写错（我们能判定）→ 调用方改请求。 |
| 401 | `AuthenticationError` | ❌ 勿自动重试 | 调用方 Key 缺失/无效（本服务的门禁）。 |
| 404 | `InvalidEndpointOrModel.NotFound` | ❌ 勿自动重试 | 任务不存在，或不属于本次请求的 Key。 |
| 429 | `QuotaExceeded` | ❌ 勿自动重试 | 账号额度耗尽（视频 3 次/天，t2v 与 i2v 共用）。 |
| 429 | `RateLimitExceeded` | ✅ 可退避重试 | 并发/节奏限流：账号池暂时排不上（退避可重试）。 |
| 429 | `ServerOverloaded` | ❌ 勿自动重试 | 上游 x5sec 风控（RGV587）：**不自动重试**，让调用方按 429 退避。 |
| 502 | `InternalServiceError` | ✅ 可退避重试 | 上游 5xx / 非 JSON / WAF 页等，本层无法归因的故障。 |
| 503 | `CredentialUnavailable` | ✅ 可退避重试 | 上游凭据铸造/续期失败 —— **部署问题，不是调用方的错**（503 语义）。 |
| 504 | `InternalServiceError` | ✅ 可退避重试 |  |

## 版本与文档

- 版本：`v0.0.25`
- 契约：`docs/INTERFACE.md`（对外）、`docs/UPSTREAM.md`（上游）——仓库内相对路径
- 相关端点：[/llms.txt](/llms.txt) · [/v1/models](/v1/models) · [/healthz](/healthz)
