跳到主要内容

图片、音频与多模态

多模态接口可以处理文字以外的内容，例如图片和音频。不同能力使用的接口并不相同，开始前应先在模型广场确认模型支持的端点类型。

任务常用接口需要的模型能力
图片理解Chat Completions、Responses、Anthropic Messages 或 Gemini支持视觉输入的对话模型
图片生成POST /v1/images/generations支持图片生成的模型
语音转文字POST /v1/audio/transcriptions支持 Transcription 的音频模型
文字转语音POST /v1/audio/speech支持 Speech 的音频模型

本页示例使用 Python 的 requests 库：

python -m pip install requests
先确认模型端点

模型名称中包含 GPT、Claude 或 Gemini，不代表它一定支持图片或音频。应以模型广场显示的端点和能力为准。

图片理解​

图片理解是把图片作为模型输入，并要求模型描述、识别或分析图片内容。常见输入方式包括：

  • 公开 HTTPS 地址：请求体较小，但上游服务必须能够直接访问该地址。
  • Base64 Data URL 或内容块：不依赖外部地址，但会明显增大请求体。

下面三个示例读取本地的 image.jpg，并使用对应协议发送图片。

OpenAI Chat Completions​

OpenAI 兼容格式在消息的 content 数组中组合文字和 image_url：

import base64
from pathlib import Path

import requests

image_base64 = base64.b64encode(Path("image.jpg").read_bytes()).decode("utf-8")

response = requests.post(
    "https://www.bita-api.com/v1/chat/completions",
    headers={"Authorization": "Bearer YOUR_BITA_API_KEY"},
    json={
        "model": "YOUR_VISION_MODEL_ID",
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": "请描述这张图片中的主要内容。",
                    },
                    {
                        "type": "image_url",
                        "image_url": {
                            "url": f"data:image/jpeg;base64,{image_base64}",
                            "detail": "auto",
                        },
                    },
                ],
            }
        ],
    },
    timeout=180,
)
response.raise_for_status()

result = response.json()
print(result["choices"][0]["message"]["content"])

使用公开图片地址时，把 image_url.url 替换为完整的 HTTPS 地址即可。detail 的可用值和实际效果取决于模型，首次调用可以省略或使用 auto。

Claude / Anthropic Messages​

Claude 原生格式使用 image 内容块，并在 source 中提供 Base64 数据：

import base64
from pathlib import Path

import requests

image_base64 = base64.b64encode(Path("image.jpg").read_bytes()).decode("utf-8")

response = requests.post(
    "https://www.bita-api.com/v1/messages",
    headers={
        "x-api-key": "YOUR_BITA_API_KEY",
        "anthropic-version": "2023-06-01",
    },
    json={
        "model": "YOUR_VISION_MODEL_ID",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "image",
                        "source": {
                            "type": "base64",
                            "media_type": "image/jpeg",
                            "data": image_base64,
                        },
                    },
                    {
                        "type": "text",
                        "text": "请描述这张图片中的主要内容。",
                    },
                ],
            }
        ],
    },
    timeout=180,
)
response.raise_for_status()

for content in response.json()["content"]:
    if content.get("type") == "text":
        print(content.get("text", ""))

media_type 必须与实际图片格式一致。例如 PNG 图片应使用 image/png，不能只修改文件扩展名。

Gemini 原生接口​

Gemini 原生格式使用 inline_data 内容块：

import base64
from pathlib import Path

import requests

image_base64 = base64.b64encode(Path("image.jpg").read_bytes()).decode("utf-8")

response = requests.post(
    "https://www.bita-api.com/v1beta/models/YOUR_VISION_MODEL_ID:generateContent",
    headers={"x-goog-api-key": "YOUR_BITA_API_KEY"},
    json={
        "contents": [
            {
                "role": "user",
                "parts": [
                    {
                        "inline_data": {
                            "mime_type": "image/jpeg",
                            "data": image_base64,
                        }
                    },
                    {
                        "text": "请描述这张图片中的主要内容。",
                    },
                ],
            }
        ]
    },
    timeout=180,
)
response.raise_for_status()

for candidate in response.json().get("candidates", []):
    for part in candidate.get("content", {}).get("parts", []):
        if "text" in part:
            print(part["text"])

图片输入建议​

  • 图片格式、文件大小、分辨率和单次图片数量限制由模型及渠道决定。
  • 小字、表格或细节较多时，尽量提供清晰原图；普通场景可以先压缩图片控制延迟和用量。
  • 使用图片 URL 时，确认地址不需要登录、Cookie 或内网访问权限。
  • Base64 数据只保留编码内容，不要包含换行或错误的 MIME 类型。
  • 多张图片应分别放入多个图片内容块，并在文字中说明比较目标。

图片会占用模型上下文并产生输入用量。具体计费应以模型广场和调用日志为准。

图片生成​

图片生成使用独立的 /v1/images/generations 接口。模型 ID 必须来自支持图片生成端点的模型。

import base64
from pathlib import Path

import requests

response = requests.post(
    "https://www.bita-api.com/v1/images/generations",
    headers={"Authorization": "Bearer YOUR_BITA_API_KEY"},
    json={
        "model": "YOUR_IMAGE_MODEL_ID",
        "prompt": "一座位于云海之上的未来图书馆，柔和晨光，建筑概念图",
        "n": 1,
    },
    timeout=300,
)
response.raise_for_status()

image = response.json()["data"][0]

if "b64_json" in image:
    Path("generated-image.png").write_bytes(
        base64.b64decode(image["b64_json"])
    )
elif "url" in image:
    image_response = requests.get(image["url"], timeout=120)
    image_response.raise_for_status()
    Path("generated-image.png").write_bytes(image_response.content)
else:
    raise RuntimeError("响应中没有图片数据")

print("图片已保存为 generated-image.png")

响应可能返回临时图片 URL，也可能返回 b64_json。示例会兼容这两种常见形式。URL 可能具有有效期，应及时下载保存。

size、quality、response_format 等可选参数并非所有模型都支持。首次测试建议只发送 model、prompt 和 n，成功后再按照模型说明添加参数。

语音转文字​

语音转文字接口使用 multipart/form-data 上传音频文件。使用 requests 的 files 参数时，不要手动设置 Content-Type，库会自动生成包含 boundary 的请求头。

from pathlib import Path

import requests

audio_path = Path("audio.mp3")

with audio_path.open("rb") as audio_file:
    response = requests.post(
        "https://www.bita-api.com/v1/audio/transcriptions",
        headers={"Authorization": "Bearer YOUR_BITA_API_KEY"},
        data={
            "model": "YOUR_TRANSCRIPTION_MODEL_ID",
        },
        files={
            "file": (audio_path.name, audio_file, "audio/mpeg"),
        },
        timeout=300,
    )

response.raise_for_status()
result = response.json()
print(result["text"])

如果上传 WAV、M4A 或其他格式，应同步修改文件名和 MIME 类型。可接受的格式、大小和时长限制以具体模型及渠道为准。

文字转语音​

文字转语音接口返回二进制音频数据，需要把 response.content 写入文件：

from pathlib import Path

import requests

response = requests.post(
    "https://www.bita-api.com/v1/audio/speech",
    headers={"Authorization": "Bearer YOUR_BITA_API_KEY"},
    json={
        "model": "YOUR_TTS_MODEL_ID",
        "voice": "YOUR_VOICE_ID",
        "input": "欢迎使用 Bita API。",
        "response_format": "mp3",
    },
    timeout=300,
)
response.raise_for_status()

Path("speech.mp3").write_bytes(response.content)
print("音频已保存为 speech.mp3")

声音 ID、输出格式和单次输入长度由具体模型决定。不要直接套用其他平台的声音名称，应查看模型详情或平台提供的模型说明。

常见问题​

现象建议检查
模型提示不支持图片模型是否支持视觉输入，接口格式和密钥分组是否匹配
上游无法读取图片 URL地址是否公开可访问，是否存在防盗链、登录或内网限制
Base64 请求失败MIME 类型、编码内容和请求体大小是否正确
返回 413图片或音频文件超过网关或上游允许的大小
图片生成没有返回 URL检查是否返回了 b64_json
音频上传返回参数错误不要手动设置 multipart 的 Content-Type；检查文件字段、模型 ID 和格式
保存的音频无法播放文件扩展名是否与 response_format 一致，响应是否实际为错误 JSON
调用成功但费用较高检查图片尺寸、细节等级、音频时长、模型价格和分组倍率

多模态请求的参数和响应差异通常比纯文本更大。接入新模型时，建议先使用一个小文件完成最小测试，再逐步增加分辨率、时长或高级参数。

下一步：Python OpenAI SDK。