HTTP / SDK / Multimodal

调用示例

以下示例使用占位模型名演示请求结构和常见参数。实际可用模型、上下文长度、图片尺寸、音频格式以控制台开放能力和上游模型文档为准。

基础请求结构

OpenAI 兼容聊天接口使用 POST /v1/chat/completions。请求体最少需要 model 和 messages，常用可选参数用于控制输出长度、多样性、结构化输出和流式返回。

curl "https://youlai.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "system", "content": "你是一个简洁、准确的助手。"},
      {"role": "user", "content": "用三句话介绍 又来AI。"}
    ],
    "temperature": 0.3,
    "top_p": 0.9,
    "max_tokens": 800,
    "stream": false
  }'

参数	作用	建议
`model`	要调用的模型名称。	必须与控制台开放模型名完全一致，不要在文档中写死可用模型清单。
`messages`	对话消息数组，常见角色为 `system`、`user`、`assistant`。	`system` 放长期规则，`user` 放当前问题，多轮对话按历史顺序追加。
`temperature`	控制随机性，值越高越发散，值越低越稳定。	客服、抽取、代码审查可用较低值；创意写作可适当提高。
`top_p`	核采样阈值，控制候选 token 的累计概率范围。	通常只调 `temperature` 或 `top_p` 其中一个，避免两者同时大幅调整。
`max_tokens`	限制本次响应最多生成的 token 数。	用于控制成本和延迟；长文、代码、推理任务需要留足输出空间。
`stream`	是否使用 SSE 流式返回。	交互式客户端建议开启，批处理或后端任务可关闭。

流式输出

当响应较长或需要边生成边展示时，设置 stream: true。服务端会按 SSE 事件分片返回，客户端需要逐块拼接内容，直到收到结束事件。

curl -N "https://youlai.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "stream": true,
    "messages": [
      {"role": "user", "content": "写一段 200 字以内的产品说明。"}
    ]
  }'

排障时先关闭 stream，确认非流式请求能成功；客户端接入稳定后再切换流式。

JSON 输出

需要稳定解析结果时，可以使用 response_format。同时必须在提示词中明确要求输出 JSON 字段，否则部分上游模型可能生成空白、解释文本或不完整 JSON。

curl "https://youlai.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "response_format": {"type": "json_object"},
    "messages": [
      {"role": "system", "content": "只输出 JSON，不要输出 Markdown。"},
      {"role": "user", "content": "把下面文字提取成 {\"title\":\"\",\"tags\":[]}：这是一篇 API 接入说明。"}
    ]
  }'

场景	推荐做法
固定字段抽取	在提示词中列出字段名、类型和缺失值处理方式。
避免截断	适当增加 `max_tokens`，并检查响应的 `finish_reason`。
兼容不同模型	如果某个上游不支持 `response_format`，退化为提示词约束并在业务侧做 JSON 校验。

Python：OpenAI SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://youlai.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[
        {"role": "system", "content": "你是 API 文档助手。"},
        {"role": "user", "content": "请生成一个 API 接入检查清单。"},
    ],
    temperature=0.2,
    max_tokens=1000,
)

print(response.choices[0].message.content)

Node.js：OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://youlai.ai/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-5.5",
  messages: [
    { role: "user", content: "给我一个 JavaScript 调用 LLM 的最小示例。" },
  ],
  temperature: 0.2,
  max_tokens: 800,
});

console.log(response.choices[0].message.content);

视觉输入

支持视觉能力的模型通常仍走聊天补全接口，但 messages[].content 从纯字符串变为多段数组。图片可以使用公网 URL，也可以按客户端支持方式传入 Base64。

curl "https://youlai.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "请描述这张图片，并提取其中可见文字。"},
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/demo.png"
            }
          }
        ]
      }
    ],
    "max_tokens": 1000
  }'

图片大小、数量、URL 可访问性和 Base64 格式限制由上游模型决定。视觉模型不可用时会返回模型不支持、多模态输入格式错误或上游 400 类错误。

图片生成

图片生成通常使用 POST /v1/images/generations。不同厂商对尺寸、质量、种子、负面提示词和输出格式的支持差异较大，具体参数见“模型参数”。

curl "https://youlai.ai/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "prompt": "一张现代办公桌上的 AI 文档站首页截图，干净、专业、真实光照",
    "size": "1024x1024",
    "n": 1,
    "response_format": "b64_json"
  }'

参数	说明
`prompt`	正向提示词，描述主体、风格、构图、文字和画面限制。
`size`	图片尺寸或比例。部分模型使用 `1024x1024`，部分模型使用 `1:1`、`16:9` 这类比例。
`n`	生成张数。并非所有模型都支持大于 1。
`response_format`	常见为 `url` 或 `b64_json`；部分模型始终返回 Base64 或任务结果 URL。
`seed`	用于近似复现结果；图像生成仍有概率性，同一 seed 不保证完全一致。

语音生成

文本转语音一般使用 POST /v1/audio/speech。核心差异在 voice、语速、音量、音高、采样率、编码格式和是否支持流式输出。

curl "https://youlai.ai/v1/audio/speech" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  --output speech.mp3 \
  -d '{
    "model": "gpt-5.5",
    "input": "欢迎使用 又来AI。这是一次语音生成测试。",
    "voice": "default",
    "response_format": "mp3",
    "speed": 1.0
  }'

音频模型的参数命名不完全统一。部分上游使用 input，部分使用 text；部分使用 response_format，部分使用 format 或 audio_setting.format。

Claude 兼容 Messages

Claude 类客户端常用 POST /v1/messages，鉴权头通常是 x-api-key。这类请求必须显式设置 max_tokens。

curl "https://youlai.ai/v1/messages" \
  -H "x-api-key: sk-xxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "max_tokens": 1024,
    "system": "你是一个安全、准确的助手。",
    "messages": [
      {
        "role": "user",
        "content": "请解释如何安全保存令牌。"
      }
    ]
  }'