混合理解 - FoxAPI

授权

Authorization

string

header

必填

所有接口均需要使用 Bearer Token 进行认证。在请求头中添加：

Authorization: Bearer YOUR_API_KEY

YOUR_API_KEY 为 API Token（sk-... 格式）。

请求体

application/json

messages[] 形态的请求体（OpenAI Chat 兼容）。除下列字段外，其他 OpenAI 兼容参数（temperature、top_p、stop、frequency_penalty 等）按 OpenAI Chat 规范使用。

model

string

必填

获取模型列表

示例:

"claude-opus-4-7"

messages

object[]

必填

OpenAI Chat 格式消息数组。messages[*].content 可为 string 或 array；array 元素 type ∈ {text, image_url, video_url, audio_url, file_url}。模型不支持的 type 返 422 model_not_support_capability。

典型 content 形态示例：

纯 text（string content，最简形式）：

[{"role": "user", "content": "count 1 to 3"}]

纯 text（array content，与多模态混用时统一格式）：

[{"role": "user", "content": [{"type": "text", "text": "count 1 to 3"}]}]

text + 图片：

[{"role": "user", "content": [
  {"type": "text", "text": "describe this image"},
  {"type": "image_url", "image_url": {"url": "https://example.com/x.png"}}
]}]

text + 视频：

[{"role": "user", "content": [
  {"type": "text", "text": "summarize this video"},
  {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}}
]}]

text + 文件：

[{"role": "user", "content": [
  {"type": "text", "text": "extract key points"},
  {"type": "file_url", "file_url": {"url": "https://example.com/doc.pdf"}}
]}]

多轮对话（system + 多轮 user/assistant）：

[
  {"role": "system", "content": "You are a terse assistant."},
  {"role": "user", "content": "1+1?"},
  {"role": "assistant", "content": "2"},
  {"role": "user", "content": "3+3?"}
]

全类型附件混合（单条 user 消息内含 image_url / video_url / audio_url / file_url 各 2 个）：

[{"role": "user", "content": [
  {"type": "text", "text": "汇总下列图片、视频、音频和文档的核心信息"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image-1.png"}},
  {"type": "image_url", "image_url": {"url": "https://example.com/image-2.jpg"}},
  {"type": "video_url", "video_url": {"url": "https://example.com/clip-1.mp4"}},
  {"type": "video_url", "video_url": {"url": "https://example.com/clip-2.mp4"}},
  {"type": "audio_url", "audio_url": {"url": "https://example.com/audio-1.mp3"}},
  {"type": "audio_url", "audio_url": {"url": "https://example.com/audio-2.wav"}},
  {"type": "file_url", "file_url": {"url": "https://example.com/doc-1.pdf"}},
  {"type": "file_url", "file_url": {"url": "https://example.com/doc-2.docx"}}
]}]

Show child attributes

示例:

[
  { "role": "user", "content": "count 1 to 3" }
]

stream

boolean

默认值:false

是否流式。

行为差异：

值	Submit 响应 `stream` 字段	SSE 端点
`false`	`null`	不可用
`true`	`{"url": "/v1/llm/generations/{task_id}/stream"}`	可用；同时 task.data 累积完整响应

示例:

false

max_tokens

integer | null

生成 token 上限。家族级约束：claude-* 必填；gpt-* 通常 ≥ 16；gemini-* 可选。

示例:

64

temperature

number | null

采样温度。

top_p

number | null

nucleus sampling。

stop

停止序列。

响应

任务已创建

Submit 响应，对齐统一任务标准形状。results / error 在 submit 阶段固定为 null，任务完成/失败后通过 GET /v1/tasks/{task_id} 返回

string

必填

任务 ID，格式 task-llm-{timestamp}-{8random}。用于 GET /v1/tasks/{task_id} 查询或 GET /v1/llm/generations/{task_id}/stream 订阅 SSE

示例:

"task-llm-1776874565-yq3szvcu"

object

enum<string>

必填

对象类型，固定 llm.generation.task

可用选项:

llm.generation.task

示例:

"llm.generation.task"

type

enum<string>

必填

媒体类型，固定 llm

可用选项:

llm

示例:

"llm"

model

string

必填

客户端提交的模型名（原样回显）

示例:

"claude-opus-4-7"

status

enum<string>

必填

任务状态，submit 阶段固定 pending

可用选项:

pending

示例:

"pending"

progress

integer

必填

进度 0-100，submit 阶段固定 0

示例:

0

created

integer

必填

创建时间（Unix 秒）

示例:

1776874565

stream

object

stream=true 时返回 {url: ...}；stream=false 时为 null。客户端据此决定是否连接 SSE

Show child attributes

results

object[] | null

submit 阶段固定 null；任务完成后通过 GET /v1/tasks/{task_id} 获取，results[0] 为完整 OpenAI ChatCompletion 响应。

已知限制：thinking 模型的推理内容（reasoning_content）仅在 SSE 流的 delta 中出现，不累积到 results[0].message.content

示例:

null

error

object

submit 阶段固定 null；任务失败时通过 GET /v1/tasks/{task_id} 返回

示例:

null