API documentationAPI 文档Documentation de l'APIDocumentación de la API

Early access.抢先体验。Accès anticipé.Acceso anticipado. This is a preview of the API: keys are issued to approved customers within 3 business days of a request, see the wholesale page.以下是接口预览：提出申请后 3 个工作日内向通过审核的客户发放 Key，详见批发页。Ceci est un aperçu de l'API : les clés sont délivrées aux clients approuvés dans les 3 jours ouvrables suivant la demande, voir la page de gros.Esto es una vista previa de la API: las claves se entregan a los clientes aprobados en un plazo de 3 días hábiles tras la solicitud, consulta la página mayorista.

The gateway exposes two familiar protocols on one host. If your code already works with OpenAI or Anthropic, you only change the base URL, the API key and the model name. 网关在同一个域名下提供两种常见协议。如果你的代码已经能调用 OpenAI 或 Anthropic，只需更换 base URL、API Key 和模型名。La passerelle expose deux protocoles courants sur un même hôte. Si votre code fonctionne déjà avec OpenAI ou Anthropic, il vous suffit de changer l'adresse de base, la clé API et le nom du modèle.La pasarela expone dos protocolos conocidos en un mismo host. Si tu código ya funciona con OpenAI o Anthropic, solo tienes que cambiar la URL base, la clave de API y el nombre del modelo.

Quickstart快速开始Démarrage rapideInicio rápido

1. Create an account and top up your balance in the console.注册账号，在控制台充值余额。Créez un compte et rechargez votre solde dans la console.Crea una cuenta y recarga tu saldo en la consola.
2. Create an API key under API keys. It is shown once; store it somewhere safe.在 API 密钥 页面创建 Key。Key 只显示一次，请妥善保存。Créez une clé API sous Clés API. Elle n'est affichée qu'une fois ; conservez-la en lieu sûr.Crea una clave de API en Claves de API. Se muestra una sola vez; guárdala en un lugar seguro.
3. Send your first request:发送第一个请求：Envoyez votre première requête :Envía tu primera solicitud:

curl {{BASE}}/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seed-2.1-lite",
    "messages": [{"role": "user", "content": "Say hello in three languages."}]
  }'

Authentication认证AuthentificationAutenticación

Send your key as a bearer token. Anthropic-style clients may use the x-api-key header instead; both work on both endpoints. 以 Bearer Token 方式传入 Key。Anthropic 风格的客户端也可使用 x-api-key 请求头；两个接口都支持两种方式。Envoyez votre clé comme jeton Bearer. Les clients de style Anthropic peuvent utiliser l'en-tête x-api-key à la place ; les deux fonctionnent sur les deux points d'accès.Envía tu clave como token Bearer. Los clientes al estilo Anthropic pueden usar en su lugar el encabezado x-api-key; ambos funcionan en los dos endpoints.

Authorization: Bearer YOUR_API_KEY
# or
x-api-key: YOUR_API_KEY

POST /v1/chat/completions

OpenAI Chat Completions format. All request fields (messages, temperature, tools, response_format, stream, …) are forwarded to the model provider unchanged, so anything the provider supports works here too. OpenAI Chat Completions 格式。所有请求字段（messages、temperature、tools、response_format、stream 等）都会原样转发给模型厂商，厂商支持的功能这里都能用。Format OpenAI Chat Completions. Tous les champs de la requête (messages, temperature, tools, response_format, stream, …) sont transmis tels quels au fournisseur du modèle : tout ce que le fournisseur prend en charge fonctionne donc ici aussi.Formato OpenAI Chat Completions. Todos los campos de la solicitud (messages, temperature, tools, response_format, stream, …) se reenvían sin cambios al proveedor del modelo, así que todo lo que el proveedor admita funciona también aquí.

Python

from openai import OpenAI

client = OpenAI(base_url="{{BASE}}/v1", api_key="YOUR_API_KEY")

resp = client.chat.completions.create(
    model="doubao-seed-2.1-pro",
    messages=[{"role": "user", "content": "Explain CRDTs in two sentences."}],
)
print(resp.choices[0].message.content)
print(resp.usage)

Streaming

stream = client.chat.completions.create(
    model="doubao-seed-2.1-pro",
    messages=[{"role": "user", "content": "Write a haiku about caching."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Streaming responses are forwarded as server-sent events. The gateway always asks the provider to include token usage in the final chunk, so billing is exact. 流式响应以 SSE 转发。网关会自动要求上游在最后一个数据块中返回 token 用量，因此计费是精确的。Les réponses en streaming sont transmises sous forme d'événements envoyés par le serveur (SSE). La passerelle demande toujours au fournisseur d'inclure la consommation de tokens dans le dernier fragment, la facturation est donc exacte.Las respuestas en streaming se reenvían como eventos enviados por el servidor (SSE). La pasarela siempre pide al proveedor que incluya el uso de tokens en el último fragmento, así que la facturación es exacta.

Node.js

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "{{BASE}}/v1", apiKey: process.env.API_KEY });
const resp = await client.chat.completions.create({
  model: "doubao-seed-2.1-lite",
  messages: [{ role: "user", content: "Hi" }],
});
console.log(resp.choices[0].message.content);

POST /v1/messages

Anthropic Messages format, served from the providers' Anthropic-compatible endpoints. Use it with the Anthropic SDK or any tool built for it. Anthropic Messages 格式，由厂商提供的 Anthropic 兼容接口转发。可配合 Anthropic SDK 或基于它的工具使用。Format Anthropic Messages, servi par les points d'accès compatibles Anthropic des fournisseurs. Utilisez-le avec le SDK Anthropic ou tout outil conçu pour lui.Formato Anthropic Messages, servido desde los endpoints compatibles con Anthropic de los proveedores. Úsalo con el SDK de Anthropic o con cualquier herramienta creada para él.

import anthropic

client = anthropic.Anthropic(base_url="{{BASE}}", api_key="YOUR_API_KEY")

msg = client.messages.create(
    model="doubao-seed-2.1-pro",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(msg.content[0].text)

Note that the Anthropic SDK appends /v1/messages itself, so the base URL has no /v1 suffix here, whereas the OpenAI SDK needs /v1. 注意：Anthropic SDK 会自行追加 /v1/messages，所以这里的 base URL 不带 /v1；而 OpenAI SDK 的 base URL 需要带 /v1。Notez que le SDK Anthropic ajoute lui-même /v1/messages : l'adresse de base n'a donc pas de suffixe /v1 ici, alors que le SDK OpenAI a besoin de /v1.Ten en cuenta que el SDK de Anthropic añade /v1/messages por sí mismo, así que la URL base no lleva el sufijo /v1 aquí, mientras que el SDK de OpenAI sí necesita /v1.

POST /v1/images/generations

Image generation (Seedream), in the same format as Volcengine's own API. Send a prompt, and optionally reference images to edit or combine. The answer lists image URLs, valid for 24 hours, so download them; or ask for response_format: "b64_json" to get the images inline.图片生成（Seedream），请求格式与火山引擎官方接口一致。传入提示词，也可以传入参考图做编辑或合成。返回结果是图片链接，24 小时内有效，请及时下载；也可以设置 response_format: "b64_json" 直接拿到图片数据。Génération d'images (Seedream), au même format que l'API de Volcengine. Envoyez un prompt et, au besoin, des images de référence à modifier ou à combiner. La réponse contient des URL d'images valables 24 heures : téléchargez-les ; ou demandez response_format: "b64_json" pour recevoir les images directement.Generación de imágenes (Seedream), con el mismo formato que la API de Volcengine. Envía un prompt y, si quieres, imágenes de referencia para editar o combinar. La respuesta incluye URLs de imágenes válidas durante 24 horas, así que descárgalas; o pide response_format: "b64_json" para recibir las imágenes directamente.

import requests

resp = requests.post(
    "{{BASE}}/v1/images/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "doubao-seedream-5.0-pro",
        "prompt": "A cat in a spacesuit, studio light",
        "size": "2K",
        "watermark": False,
    },
    timeout=300,
)
print(resp.json()["data"][0]["url"])

• size: "1K", "2K", "4K" or an exact size such as "2048x2048". Larger than about 1.5K costs more on Seedream 5.0 Pro.size："1K"、"2K"、"4K"，或具体尺寸如 "2048x2048"。Seedream 5.0 Pro 超过约 1.5K 的图片更贵。size : "1K", "2K", "4K" ou une taille exacte comme "2048x2048". Au-delà d'environ 1,5K, c'est plus cher sur Seedream 5.0 Pro.size: "1K", "2K", "4K" o un tamaño exacto como "2048x2048". Por encima de 1,5K cuesta más en Seedream 5.0 Pro.
• image: a URL or a base64 string, or a list of up to 10, to edit or combine images.image：图片链接或 base64 字符串，也可以是最多 10 张的列表，用于编辑或合成。image : une URL ou une chaîne base64, ou une liste d'au plus 10, pour modifier ou combiner des images.image: una URL o una cadena base64, o una lista de hasta 10, para editar o combinar imágenes.
• watermark: the model adds a watermark by default. Send false to turn it off.watermark：模型默认会加水印，传 false 可以关闭。watermark : le modèle ajoute un filigrane par défaut. Envoyez false pour le désactiver.watermark: el modelo añade una marca de agua por defecto. Envía false para quitarla.
• layer_decomposition (Seedream 5.0 Pro): split one image into separate layers. stream is not supported.layer_decomposition（Seedream 5.0 Pro）：把一张图拆成多个图层。不支持 stream。layer_decomposition (Seedream 5.0 Pro) : sépare une image en plusieurs calques. stream n'est pas pris en charge.layer_decomposition (Seedream 5.0 Pro): divide una imagen en capas. stream no está soportado.

Video generation视频生成Génération de vidéoGeneración de video

Video generation (Seedance) takes a while, so it works in three steps: start a task, check on it, download the result. The paths are the same as Volcengine's own API.视频生成（Seedance）需要一段时间，所以分三步：创建任务、查询任务、下载结果。接口路径与火山引擎官方一致。La génération de vidéo (Seedance) prend du temps ; elle se fait donc en trois étapes : créer une tâche, la consulter, télécharger le résultat. Les chemins sont les mêmes que ceux de l'API de Volcengine.La generación de video (Seedance) tarda un rato, así que se hace en tres pasos: crear una tarea, consultarla y descargar el resultado. Las rutas son las mismas que las de la API de Volcengine.

import time, requests

BASE, HEADERS = "{{BASE}}/v1", {"Authorization": "Bearer YOUR_API_KEY"}

# 1. start the task
task = requests.post(f"{BASE}/contents/generations/tasks", headers=HEADERS, json={
    "model": "doubao-seedance-2.0",
    "content": [{"type": "text", "text": "A cat on a skateboard, cinematic"}],
    "resolution": "720p",
    "duration": 5,
}).json()

# 2. check until it is done (usually a minute or two)
while True:
    info = requests.get(f"{BASE}/contents/generations/tasks/{task['id']}", headers=HEADERS).json()
    if info["status"] in ("succeeded", "failed", "cancelled", "expired"):
        break
    time.sleep(10)

# 3. download the video (the link works for 24 hours)
if info["status"] == "succeeded":
    print(info["content"]["video_url"])

• content: a list that mixes text with image_url (first frame, last frame or reference images) and video_url (reference or a video to extend).content：由 text、image_url（首帧、尾帧或参考图）、video_url（参考视频或待延长的视频）组成的列表。content : une liste qui mêle text, image_url (première image, dernière image ou images de référence) et video_url (référence ou vidéo à prolonger).content: una lista que combina text, image_url (primer fotograma, último fotograma o imágenes de referencia) y video_url (referencia o video a extender).
• resolution (480p, 720p, 1080p, and 4k on Seedance 2.0), ratio (for example 16:9), duration in seconds (4 to 15; up to 30 on Seedance 2.5), generate_audio, watermark and seed are forwarded as they are.resolution（480p、720p、1080p，Seedance 2.0 还有 4k）、ratio（如 16:9）、duration（秒，4～15；Seedance 2.5 最长 30）、generate_audio、watermark、seed 都会原样转发。resolution (480p, 720p, 1080p, et 4k sur Seedance 2.0), ratio (par exemple 16:9), duration en secondes (4 à 15 ; jusqu'à 30 sur Seedance 2.5), generate_audio, watermark et seed sont transmis tels quels.resolution (480p, 720p, 1080p, y 4k en Seedance 2.0), ratio (por ejemplo 16:9), duration en segundos (4 a 15; hasta 30 en Seedance 2.5), generate_audio, watermark y seed se reenvían tal cual.
• Statuses: queued, running, succeeded, failed, cancelled, expired. DELETE /v1/contents/generations/tasks/{id} cancels a queued task; GET /v1/contents/generations/tasks lists your own tasks.状态有 queued、running、succeeded、failed、cancelled、expired。DELETE /v1/contents/generations/tasks/{id} 可以取消排队中的任务；GET /v1/contents/generations/tasks 列出你自己的任务。Statuts : queued, running, succeeded, failed, cancelled, expired. DELETE /v1/contents/generations/tasks/{id} annule une tâche en file d'attente ; GET /v1/contents/generations/tasks liste vos propres tâches.Estados: queued, running, succeeded, failed, cancelled, expired. DELETE /v1/contents/generations/tasks/{id} cancela una tarea en cola; GET /v1/contents/generations/tasks lista tus propias tareas.
• Up to 3 unfinished videos per account at a time. The tools option (web search) is not available.每个账号同时最多有 3 个未完成的视频任务。不支持 tools 选项（联网搜索）。Au plus 3 vidéos non terminées par compte à la fois. L'option tools (recherche web) n'est pas disponible.Hasta 3 videos sin terminar por cuenta a la vez. La opción tools (búsqueda web) no está disponible.

Claude Code & IDE toolsClaude Code 与 IDE 工具Claude Code & outils d'IDEClaude Code & herramientas de IDE

Tools that accept a custom Anthropic or OpenAI endpoint can use the gateway. For Claude Code, set these environment variables: 支持自定义 Anthropic 或 OpenAI 接口地址的工具都可以接入。Claude Code 请设置以下环境变量：Les outils qui acceptent un point d'accès Anthropic ou OpenAI personnalisé peuvent utiliser la passerelle. Pour Claude Code, définissez ces variables d'environnement :Las herramientas que aceptan un endpoint personalizado de Anthropic u OpenAI pueden usar la pasarela. Para Claude Code, define estas variables de entorno:

export ANTHROPIC_BASE_URL="{{BASE}}"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
export ANTHROPIC_MODEL="doubao-seed-2.1-pro"
export ANTHROPIC_SMALL_FAST_MODEL="doubao-seed-2.1-lite"
claude

For OpenAI-style tools (Cursor, Cline, Continue, Open WebUI, …) choose "OpenAI-compatible" or "custom provider", then enter {{BASE}}/v1 as the base URL, your key, and a model ID from the table below. 对于 OpenAI 风格的工具（Cursor、Cline、Continue、Open WebUI 等），选择“OpenAI 兼容”或“自定义提供商”，填入 {{BASE}}/v1 作为 base URL，再填你的 Key 和下表中的模型 ID。Pour les outils de style OpenAI (Cursor, Cline, Continue, Open WebUI, …), choisissez « compatible OpenAI » ou « fournisseur personnalisé », puis saisissez {{BASE}}/v1 comme adresse de base, votre clé et un identifiant de modèle du tableau ci-dessous.Para herramientas al estilo OpenAI (Cursor, Cline, Continue, Open WebUI, …) elige «compatible con OpenAI» o «proveedor personalizado» y escribe {{BASE}}/v1 como URL base, tu clave y un ID de modelo de la tabla de abajo.

Models模型ModèlesModelos

Use the Model ID as the model parameter. GET /v1/models returns the current list. Prices are USD per 1M tokens. 将 模型 ID 作为 model 参数。GET /v1/models 返回当前列表。价格单位为美元 / 每百万 token。Utilisez l'ID du modèle comme paramètre model. GET /v1/models renvoie la liste actuelle. Les prix sont en USD par million de tokens.Usa el ID del modelo como parámetro model. GET /v1/models devuelve la lista actual. Los precios son en USD por millón de tokens.

GET /v1/models lists chat models; add ?type=all to include image and video models.GET /v1/models 默认只列出对话模型；加上 ?type=all 可包含图片和视频模型。GET /v1/models liste les modèles de chat ; ajoutez ?type=all pour inclure les modèles d'image et de vidéo.GET /v1/models lista los modelos de chat; añade ?type=all para incluir los de imagen y video.

Billing计费FacturationFacturación

• Prepaid USD balance. Each successful request deducts (uncached input × input price) + (cached input × cached price) + (output × output price).预付美元余额。每次成功请求扣费 = 未缓存输入 × 输入价 + 缓存输入 × 缓存价 + 输出 × 输出价。Solde prépayé en USD. Chaque requête réussie débite (entrée hors cache × prix d'entrée) + (entrée en cache × prix du cache) + (sortie × prix de sortie).Saldo prepago en USD. Cada solicitud exitosa descuenta (entrada sin caché × precio de entrada) + (entrada en caché × precio de caché) + (salida × precio de salida).
• Cached input is the part of your prompt the provider served from its prompt cache. Keep a stable prefix (system prompt, documents) at the start of the prompt to benefit.缓存输入是指上游从其提示词缓存中读取的那部分。把稳定的内容（系统提示、文档）放在提示词开头可提高命中率。L'entrée en cache est la partie de votre prompt que le fournisseur a servie depuis son cache de prompts. Placez un préfixe stable (prompt système, documents) au début du prompt pour en profiter.La entrada en caché es la parte de tu prompt que el proveedor sirvió desde su caché de prompts. Mantén un prefijo estable (prompt del sistema, documentos) al inicio del prompt para aprovecharlo.
• Reasoning / thinking tokens are part of the output and are billed as output.推理 / 思考 token 属于输出，按输出价计费。Les tokens de raisonnement / de réflexion font partie de la sortie et sont facturés comme tels.Los tokens de razonamiento / pensamiento forman parte de la salida y se facturan como salida.
• Images: charged per image produced, by size (up to about 1.5K is cheaper). Extra reference images and layers have their own prices, see the model table. Images that fail are free.图片：按实际生成的张数计费，按尺寸分档（约 1.5K 及以下更便宜）。额外的参考图和图层另有价格，见模型表。生成失败的不收费。Images : facturées par image produite, selon la taille (jusqu'à environ 1,5K, c'est moins cher). Les images de référence supplémentaires et les calques ont leur propre prix, voir le tableau des modèles. Les images en échec sont gratuites.Imágenes: se cobran por imagen generada, según el tamaño (hasta aproximadamente 1,5K es más barato). Las imágenes de referencia adicionales y las capas tienen su propio precio; consulta la tabla de modelos. Las imágenes fallidas son gratis.
• Video: charged per 1M output tokens, once the video is ready. Tokens are about width × height × 24 × seconds ÷ 1024, so a 5-second 720p clip is 108,000 tokens. While a video is being made, an estimate of its price is held (not charged) from your balance. Failed, cancelled and expired videos are free.视频：视频生成完成后，按每百万输出 token 计费。token 数约等于 宽 × 高 × 24 × 秒数 ÷ 1024，5 秒 720p 视频约 108,000 token。生成期间会从余额中预留（不扣除）一笔预估费用。失败、取消和过期的视频不收费。Vidéo : facturée par million de tokens de sortie, une fois la vidéo prête. Les tokens valent environ largeur × hauteur × 24 × secondes ÷ 1024 : un clip de 5 secondes en 720p fait 108 000 tokens. Pendant la génération, une estimation du prix est réservée (non débitée) sur votre solde. Les vidéos en échec, annulées ou expirées sont gratuites.Video: se cobra por millón de tokens de salida, cuando el video está listo. Los tokens son aproximadamente ancho × alto × 24 × segundos ÷ 1024: un clip de 5 segundos en 720p son 108 000 tokens. Mientras se genera, se reserva (sin cobrar) una estimación del precio de tu saldo. Los videos fallidos, cancelados o caducados son gratis.
• Requests that fail (any 4xx/5xx) are not charged. If a stream is cut off before the provider reports usage, the request is billed on an estimate.失败的请求（任何 4xx/5xx）不收费。如果流在上游返回用量前被中断，则按估算值计费。Les requêtes qui échouent (tout 4xx/5xx) ne sont pas facturées. Si un flux est interrompu avant que le fournisseur communique la consommation, la requête est facturée sur une estimation.Las solicitudes que fallan (cualquier 4xx/5xx) no se cobran. Si un flujo se corta antes de que el proveedor informe el uso, la solicitud se factura según una estimación.
• The usage log in the console lists every request with its exact token counts and cost.控制台的用量日志会逐条列出每次请求的精确 token 数和费用。Le journal de consommation de la console liste chaque requête avec son nombre exact de tokens et son coût.El registro de consumo de la consola enumera cada solicitud con su número exacto de tokens y su costo.

Errors & limits错误与限制Erreurs & limitesErrores & límites

Errors use the shape of the protocol you called: {"error": {"message", "type", "code"}} on /v1/chat/completions and {"type": "error", "error": {…}} on /v1/messages. 错误响应沿用你所调用协议的格式：/v1/chat/completions 为 {"error": {"message", "type", "code"}}，/v1/messages 为 {"type": "error", "error": {…}}。Les erreurs suivent le format du protocole appelé : {"error": {"message", "type", "code"}} sur /v1/chat/completions et {"type": "error", "error": {…}} sur /v1/messages.Los errores usan el formato del protocolo que llamaste: {"error": {"message", "type", "code"}} en /v1/chat/completions y {"type": "error", "error": {…}} en /v1/messages.

Every response carries an x-relay-request-id header. Quote it if you contact support.每个响应都带有 x-relay-request-id 头，联系客服时请附上。Chaque réponse contient un en-tête x-relay-request-id. Indiquez-le si vous contactez l'assistance.Cada respuesta incluye un encabezado x-relay-request-id. Indícalo si contactas con soporte.