Skip to content
byteplus.cc
docs

文档

面向字节跳动豆包、Seedance、Seedream 模型的统一 OpenAI 兼容接口。

base_url: https://byteplus.cc/v1
01

快速开始

任何 OpenAI SDK 都可以原样使用——只需改 base URL 与模型 id。密钥按项目隔离，可无停机轮换。

  1. 1创建账号，并在控制台生成密钥。
  2. 2把 base URL 设为 https://byteplus.cc/v1。
  3. 3使用字节模型 id，例如 doubao-seed-1-6。
quickstart
# any OpenAI-compatible client works
pip install openai
export BYTEPLUS_KEY="bp_live_xxxxxxxxxxxxxxxx"
02

鉴权

把密钥作为 Bearer Token 发送。缺少密钥返回 401；超出配额返回 429，并带 retry-after 响应头。

authentication
curl https://byteplus.cc/v1/chat/completions \
  -H "Authorization: Bearer $BYTEPLUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-pro-32k","messages":[{"role":"user","content":"hi"}]}'

# 401  invalid_api_key
# 429  rate_limit_exceeded   (see retry-after header)
03

对话补全

POST /v1/chat/completions 接受标准 OpenAI 请求体：model、messages、temperature、max_tokens、stream 与 tools。

chat
from openai import OpenAI

client = OpenAI(
    base_url="https://byteplus.cc/v1",
    api_key=os.environ["BYTEPLUS_KEY"],
)

stream = client.chat.completions.create(
    model="doubao-seed-1-6",
    messages=[{"role": "user", "content": "Summarise this deck."}],
    temperature=0.7,
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
04

视频任务

视频为异步接口：先创建任务，再轮询或等待回调。任务 id 稳定，结果保留 24 小时可随时取回。

video
# 1. create the task
curl https://byteplus.cc/v1/video/tasks \
  -H "Authorization: Bearer $BYTEPLUS_KEY" \
  -d '{
    "model": "seedance-1-0-pro",
    "prompt": "neon koi in a datacenter, dolly-in",
    "resolution": "1080p",
    "duration": 5
  }'
# => {"id": "task_9f2c", "status": "queued"}

# 2. poll for the artifact
curl https://byteplus.cc/v1/video/tasks/task_9f2c \
  -H "Authorization: Bearer $BYTEPLUS_KEY"
# => {"status": "succeeded", "video_url": "https://..."}
05

图像生成

POST /v1/images/generations 按文本提示词批量出图；POST /v1/images/edits 对已有图片执行指令式编辑。

image
curl https://byteplus.cc/v1/images/generations \
  -H "Authorization: Bearer $BYTEPLUS_KEY" \
  -d '{
    "model": "seedream-4-0",
    "prompt": "isometric mint server garden, 4K",
    "size": "4096x4096",
    "n": 4
  }'
06

模型列表

GET /v1/models 返回全部模型 id，以及各自的模态、上下文窗口与单位价格。

models
curl https://byteplus.cc/v1/models \
  -H "Authorization: Bearer $BYTEPLUS_KEY"

# => {"data": [
#      {"id": "doubao-seed-1-6", "modality": "language", "context": 262144},
#      {"id": "seedance-1-0-pro", "modality": "video", "max_duration": 10},
#      {"id": "seedream-4-0",    "modality": "image", "max_size": "4096x4096"}
#    ]}
07

错误码

错误遵循 OpenAI 结构：包含 type、code、message、param 的 error 对象。遇到 429 与 5xx 请指数退避重试。

401invalid_api_key检查 Bearer Token 以及密钥是否处于启用状态。
402insufficient_balance请先为账户余额充值。
404model_not_found对照 GET /v1/models 校验模型 id。
422invalid_request查看错误的 param 字段并修正请求体。
429rate_limit_exceeded退避后重试，或预留并发量。
503capacity_unavailable按 retry-after 窗口重试；队列位置在响应头中。
08

速率限制

限额按密钥、按模型执行，以每分钟请求数与每分钟 token 数表示。预留客户享有专属并发池。

PricingConsole