媒体输入 · TokenToSea 开发者文档

很多型号可以理解图片、音频、视频或文档。本页说明如何把这些媒体交给模型，以及平台对媒体的要求。

前提：已创建密钥并把它设置为环境变量 TOKENTOSEA_API_KEY。示例需要你自己的公网 HTTPS 图片地址与一段本地音频文件。

先确认型号接受这种输入#

每个型号、每个接口、每种响应方式接受的输入类型都单独验收。GET /v1/models 的 verified_inputs 给出明细，例如：

JSON

{
  "id": "qwen3.8-flash",
  "verified_inputs": {
    "/v1/chat/completions": { "json": ["text", "image"], "sse": ["text", "image"] }
  }
}

可能的取值为 text、image、audio、video、document。请求中出现未列出的类型时返回 422 input_modality_not_verified。

媒体放在请求的哪里#

接口	传入方式
`/v1/chat/completions`	`messages[].content` 中的内容块，例如 `{"type": "image_url", "image_url": {"url": "https://…"}}`；音频、视频块只在型号开放时可用
`/v1/messages`	Anthropic 内容块，例如 `{"type": "image", "source": {…}}`
`/v1/responses`	`input` 中的 `{"type": "input_image", "image_url": "https://…"}` 等块
`/v1/images/edits`	`image`（原图 URL），可选 `mask`
`/v1/videos`	`input[]`，每项为 `{"role": "…", "url": "https://…"}`，见视频输入角色
`/v1/audio/transcriptions`	multipart 上传 `file`，或 JSON 中的 `file_url`
`/v1/embeddings`（多模态型号）	`input` 数组中的图文条目，格式见向量参考
`/v1/systemone`	请求体内嵌的 base64，见 System One 指南

各接口的完整字段见 API 参考，各型号的可运行示例见模型目录。

URL 要求#

大多数媒体以 URL 传入，并由厂商或平台下载：

使用 HTTPS，地址公网可访问，不需要登录或 Cookie；
不包含用户名或密码；不能指向 localhost、内网或保留地址；
平台下载的媒体不跟随 HTTP 跳转，请直接给出最终地址；
使用签名链接时，有效期要覆盖整个处理过程（异步任务可能持续数分钟）；
只提交你有权使用、且同意交给厂商处理的素材。

平台会自己下载并检查以下媒体：视频输入（测量时长用于计价）、语音识别型号的音频 URL、异步向量的输入文件。图片通常由厂商直接下载。

下载失败#

情况	返回
平台下载时收到非 2xx 响应或跳转	`422 input_media_unavailable`
地址不是公网 HTTPS、下载超过 60 秒或超过 75 MiB	请求失败，可能返回 `502 execution_result_pending`
时长无法识别或超过 1 小时	`422 media_duration_invalid`

这些失败都发生在预留之前，不会产生调用记录或费用，用原键查询结果会返回 404。修正地址后重新发起即可。

数量与大小限制#

限制	值
单次请求图片	最多 20 张
单次请求视频	最多 8 段
单次请求媒体总数	最多 30 个
平台下载的单个媒体	最大 75 MiB
单段音频、视频时长	最长 1 小时
multipart 上传	1 个文件，最大 25 MB
JSON 请求体（含内嵌 base64）	最大 48 MB

厂商自身可能有更严格的分辨率、时长或格式限制，以型号页面与厂商文档为准。含媒体的请求按型号最大输入量预留金额，请保持足够的可用余额。

示例：图片理解#

qwen3.8-flash 的 Chat Completions 接受图片输入。把 IMAGE_URL 换成你自己的公网 HTTPS 图片地址：

export IMAGE_URL="https://你的域名/photo.jpg"

curl https://api.tokentosea.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{
    \"model\": \"qwen3.8-flash\",
    \"max_tokens\": 512,
    \"messages\": [{
      \"role\": \"user\",
      \"content\": [
        {\"type\": \"text\", \"text\": \"描述这张图片的主要内容。\"},
        {\"type\": \"image_url\", \"image_url\": {\"url\": \"$IMAGE_URL\"}}
      ]
    }]
  }"

import os
import uuid

from openai import OpenAI

IMAGE_URL = os.environ["IMAGE_URL"]  # 你的公网 HTTPS 图片地址

client = OpenAI(api_key=os.environ["TOKENTOSEA_API_KEY"], base_url="https://api.tokentosea.com/v1", max_retries=0)
completion = client.chat.completions.create(
    model="qwen3.8-flash",
    max_tokens=512,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "描述这张图片的主要内容。"},
            {"type": "image_url", "image_url": {"url": IMAGE_URL}},
        ],
    }],
    extra_headers={"Idempotency-Key": str(uuid.uuid4())},
)
print(completion.choices[0].message.content)

import { randomUUID } from 'node:crypto';

const IMAGE_URL = process.env.IMAGE_URL; // 你的公网 HTTPS 图片地址

const response = await fetch('https://api.tokentosea.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOKENTOSEA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': randomUUID(),
  },
  body: JSON.stringify({
    model: 'qwen3.8-flash',
    max_tokens: 512,
    messages: [{
      role: 'user',
      content: [
        { type: 'text', text: '描述这张图片的主要内容。' },
        { type: 'image_url', image_url: { url: IMAGE_URL } },
      ],
    }],
  }),
});
const body = await response.json();
console.log(response.status, body.choices?.[0]?.message?.content ?? body);

上传文件：multipart#

语音识别等接口支持直接上传文件。规则：

文件字段名必须是 file，每个请求 1 个文件，最大 25 MB；其他字段最多 40 个，每个最大 1 MB。
为文件部分设置正确的 Content-Type（如 audio/wav、audio/mpeg），平台据此识别格式。语音识别支持 WAV、MP3、M4A、OGG 与 FLAC，具体以型号为准。
需要结构化值的字段（messages、input、parameters、content、provider_options、voice_setting、audio_setting）可以写成 JSON 字符串；stream、n、duration、speed、sample_rate 会按 JSON 解析。

下面用 qwen3-asr-flash 转写一段本地 WAV 文件：

curl https://api.tokentosea.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'model=qwen3-asr-flash' \
  -F 'file=@your-audio.wav;type=audio/wav'

import os
import uuid

import requests

with open("your-audio.wav", "rb") as audio:
    response = requests.post(
        "https://api.tokentosea.com/v1/audio/transcriptions",
        headers={
            "Authorization": f"Bearer {os.environ['TOKENTOSEA_API_KEY']}",
            "Idempotency-Key": str(uuid.uuid4()),
        },
        data={"model": "qwen3-asr-flash"},
        files={"file": ("your-audio.wav", audio, "audio/wav")},
        timeout=(10, 600),
    )
print(response.status_code, response.json())

import { randomUUID } from 'node:crypto';
import { readFile } from 'node:fs/promises';

const form = new FormData();
form.set('model', 'qwen3-asr-flash');
form.set('file', new Blob([await readFile('your-audio.wav')], { type: 'audio/wav' }), 'your-audio.wav');

const response = await fetch('https://api.tokentosea.com/v1/audio/transcriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOKENTOSEA_API_KEY}`,
    'Idempotency-Key': randomUUID(),
  },
  body: form,
});
console.log(response.status, await response.json());

上传的音频由平台转存到私有存储后交给厂商。返回结构见语音识别参考。

视频输入角色#

/v1/videos 的 input[] 用 role 说明每个素材的用途：

`role`	含义
`first_frame`	首帧图片（图生视频）
`last_frame`	尾帧图片（首尾帧生成）
`reference_image`	参考图片（主体、风格参考）
`reference_video`	参考视频（视频编辑、动作参考）
`reference_audio`	参考音频（音频驱动）

每个型号只接受其中的一部分；不支持的角色返回 422 unsupported_video_role 或 video_input_invalid。每个型号的正确写法见其页面中的视频示例。

平台文件与音色#

部分型号需要先创建平台资源，再在模型调用中引用：

资源	创建	引用方式	用于
文件 `file_tts_…`	`POST /v1/files`（multipart：`model`、`purpose`、`file`）	`file_id`、`text_file_id`，或在消息中写 `fileid://file_tts_…`	文档理解（`purpose=file-extract`）、音色复刻输入（`voice-clone-input`）、MiniMax 异步语音合成文本（`t2a_async_input`）
音色 `voice_tts_…`	`POST /v1/audio/voices`（`model`、`audio_url`，可选 `language_hints`）	`voice`	对应型号的语音合成

资源只能由创建它的密钥使用，且只能用于同一服务商（音色还需同一型号）；否则返回 404 resource_not_found 或 422 voice_model_mismatch。
这些字段只接受本平台签发的 ID，不接受厂商原始 ID（422 use_owned_platform_resource）。
文件 30 天后过期；每账号每天最多上传 100 次文件、创建 20 个音色。

接口详情见文件参考与音色参考。

复用生成结果#

TokenToSea 生成的图片、视频等文件可以作为后续请求的输入（例如先文生图，再用这张图做图生视频）。使用结果中的签名 url 即可：需要平台下载的媒体（如视频）由平台直接读取你自己的资产，其他媒体由厂商按链接下载。签名链接最长 300 秒有效，请在提交前用 GET /v1/assets/{asset_id}/download-url 获取新链接，见异步任务与结果。