开放 API 文档

将平台的图片、视频、文案创作能力接入你自己的应用

接入指南

Base URL
https://<你的域名>/openapi/v1

所有开放接口均以 /openapi/v1 为前缀。

鉴权方式
Authorization: Bearer sk-xxxx

也支持 X-API-Key: sk-xxxx 请求头。

计费说明

开放API复用平台算力体系（1元 = 100算力）。图片/视频按次按规格计费，文案按token计费；调用失败自动退回算力，保证不成功不扣费。

响应结构

统一返回 { code, message, data } 包裹结构，code=200 表示成功，业务错误码见「错误码」章节。

1
注册平台账号

在万相灵创AI完成注册并登录，开放API复用平台账号的算力余额。

2
充值算力

在站内购买算力套餐（1元 = 100算力），OpenAPI调用与站内创作共用同一账户余额。

3
创建应用与API Key

在站内侧边栏「开发者中心」创建应用并生成API Key（sk-开头）。明文Key仅创建时展示一次，请妥善保管。

4
调用测试

使用下方快速开始示例发起第一次调用，建议先从「查询模型列表」接口开始验证鉴权。

5
正式上线

处理好错误码与重试逻辑后上线。建议传入 X-Request-Id 便于排查问题。

安全提醒：请勿在浏览器前端代码或公开仓库中暴露 API Key，建议在后端服务中保管。Key泄露请立即禁用并轮换。

快速开始

以「查询模型列表」和「图片生成」为例，复制以下示例并替换你的 API Key，即可完成第一次调用。

图片生成
同步返回 · 图生图/多图融合
视频生成
异步任务 · 提交后轮询
文案生成
同步/SSE流式 · 多轮对话
第一步：验证鉴权（查询模型列表）
cURL
curl -X GET "https://api.example.com/openapi/v1/models?type=image" \
  -H "Authorization: Bearer sk-your-api-key"
第二步：发起第一次图片生成
cURL
curl -X POST "https://api.example.com/openapi/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "modelCode": "seedream-4.0",
    "prompt": "一只穿着宇航服的橘猫，漂浮在星空中",
    "aspectRatio": "1:1",
    "number": 1
  }'

API 参考

共开放 7 个接口，均需通过 API Key 鉴权。参数命名与下述文档一致。

GET/openapi/v1/models

查询模型列表

获取平台对外开放的模型清单，可通过 type 参数按能力类型筛选。

请求参数
参数类型必填说明
typestring必填模型类型：image-图像 / video-视频 / text-文案
请求示例
cURL
curl -X GET "https://api.example.com/openapi/v1/models?type=image" \
  -H "Authorization: Bearer sk-your-api-key"
成功响应示例
json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "model_code": "seedream-4.0",
      "name": "Seedream 4.0",
      "description": "高质量图像生成模型",
      "model_type": 1
    }
  ]
}
POST/openapi/v1/images/generations

图片生成（同步）

提交图片生成请求，服务端完成风控、算力扣减与上游调用，同步返回图片URL列表。上游失败时已扣算力自动退回。

请求参数
参数类型必填说明
modelCodestring必填模型编码
promptstring必填提示词（支持中英文，≤2000字）
sizestring否分辨率规格：1K/2K/3K/4K 或像素值如2048x2048，默认 1K
aspectRatiostring否宽高比：1:1 / 3:4 / 4:3 / 9:16 / 16:9 / 2:3 / 3:2 / 21:9
numberinteger否生成数量 1-8，默认 1
imagesstring[]否参考图URL列表（图生图/多图融合模式）
watermarkboolean否是否添加水印，默认 false

modelCode 需通过「查询模型列表」获取。多张图 number 会按张数计费。

请求示例
cURL
curl -X POST "https://api.example.com/openapi/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "modelCode": "seedream-4.0",
    "prompt": "一只穿着宇航服的橘猫，漂浮在星空中",
    "aspectRatio": "1:1",
    "number": 1
  }'
成功响应示例
json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "images": [
      { "url": "https://cdn.example.com/xxx.jpeg", "compressed_url": "https://cdn.example.com/xxx_s.jpeg" }
    ],
    "created": 1765300000,
    "credits_used": 320
  }
}
POST/openapi/v1/videos/generations

视频生成（异步提交）

提交视频生成任务，服务端完成风控与算力预扣后立即返回 task_id，结果需通过任务查询接口轮询获取。

请求参数
参数类型必填说明
modelCodestring必填模型编码
promptstring必填提示词（建议≤500字）
ratiostring否宽高比：16:9 / 9:16 / 1:1 / adaptive，默认 adaptive
durationstring否时长：auto 或 4~15（秒），默认 auto
resolutionstring否分辨率：720P / 1080P / 480P，默认 720P
imagesstring[]否参考图URL列表（图生视频）
firstFrameUrlstring否首帧图片URL（首尾帧模式）
lastFrameUrlstring否尾帧图片URL（首尾帧模式）

提交成功即完成算力扣减；任务最终失败（status=failed）时算力自动退回。

请求示例
cURL
curl -X POST "https://api.example.com/openapi/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "modelCode": "seedance-pro",
    "prompt": "赛博朋克城市夜景，霓虹灯闪烁，镜头缓慢推进",
    "ratio": "16:9",
    "duration": "5",
    "resolution": "720P"
  }'
成功响应示例
json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "task_id": "vt_9f3a8b7c",
    "status": "submitted",
    "created": 1765300000,
    "credits_used": 1200
  }
}
GET/openapi/v1/videos/generations/{taskId}

查询视频任务

根据提交时返回的 task_id 查询视频任务状态与结果。

请求参数
参数类型必填说明
taskIdstring必填路径参数，提交接口返回的任务ID

status 取值：processing-生成中 / succeed-成功（video_url返回视频地址） / failed-失败（算力已退回）。建议每3秒轮询一次。

请求示例
cURL
curl -X GET "https://api.example.com/openapi/v1/videos/generations/vt_9f3a8b7c" \
  -H "Authorization: Bearer sk-your-api-key"
成功响应示例
json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "status": "succeed",
    "video_url": "https://cdn.example.com/video.mp4",
    "syncing": true
  }
}
POST/openapi/v1/text/completions

文案生成（同步/流式）

基于 messages 数组生成文案。stream=false 同步返回完整文本；stream=true 以 SSE 流式返回，事件名：token（文本增量）/ done（结束）/ error（错误）。

请求参数
参数类型必填说明
modelstring必填模型编码（type=text 的模型）
messagesobject[]必填消息数组，元素含 role（system/user/assistant）与 content
streamboolean否是否流式返回，默认 false
conversationIdinteger否对话ID（多轮对话时传入；为空则新建对话）

文案按token计费。多轮对话传入上次响应的 conversation_id 即可延续上下文；P0 约定以最后一条 user 消息作为本次输入。

请求示例
cURL
curl -X POST "https://api.example.com/openapi/v1/text/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3",
    "messages": [
      { "role": "system", "content": "你是专业的游戏文案策划" },
      { "role": "user", "content": "为武侠手游写一句主宣传语" }
    ],
    "stream": false
  }'
成功响应示例
json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "conversation_id": 1024,
    "content": "一剑江湖行，万里侠客梦。"
  }
}
GET/openapi/v1/credits/balance

查询算力余额

查询当前API Key绑定账户的算力余额与消耗情况，用于调用前检查与对账。

请求参数
参数类型必填说明
请求示例
cURL
curl -X GET "https://api.example.com/openapi/v1/credits/balance" \
  -H "Authorization: Bearer sk-your-api-key"
成功响应示例
json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "balance": 8800,
    "today_usage": 1200,
    "total_earned": 10000,
    "total_spent": 1200
  }
}
POST/openapi/v1/credits/estimate

预估算力消耗

按模型与参数预计算一次调用的算力消耗，不做实际扣减。参数与对应生成接口保持同名，仅传需要的字段。

请求参数
参数类型必填说明
modelCodestring必填模型编码
sizestring否图像分辨率规格（如图像的1K/2K/4K）
aspectRatiostring否图像宽高比
numberinteger否图像生成数量（默认1）
resolutionstring否视频分辨率（720P/1080P/480P）
durationstring否视频时长（auto/4~15秒）
versionstring否视频速度版本（如标准/快速）
promptTextstring否文案输入文本（用于粗估token）

文案场景可传 promptText 粗估 token 计费；图像传 size/aspectRatio/number；视频传 resolution/duration。

请求示例
cURL
curl -X POST "https://api.example.com/openapi/v1/credits/estimate" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "modelCode": "seedream-4.0",
    "aspectRatio": "1:1",
    "number": 1
  }'
成功响应示例
json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "estimated_credits": 320,
    "billing_mode": 1,
    "billing_mode_label": "按次",
    "formula": "基础算力 320 × 数量 1",
    "is_sufficient": true,
    "remaining_after_deduct": 8480
  }
}

模型与参数

当前平台全部生效模型及其可选参数档位，调用时传参取值以下述为准（也可通过 GET /models 实时查询）；参数缺省时使用模型默认值。

模型参数加载中...

错误码

业务码HTTP状态含义处理建议
200200成功—
4011401缺少或无效的API Key检查 Authorization: Bearer <key> 请求头是否正确
4012403API Key已禁用或过期在开发者中心启用密钥或重新生成
4013429触发限流（超过Key的QPS阈值）按 Retry-After 响应头进行退避重试
4101400参数校验失败根据 message 修正请求参数
4002200算力不足（data.needRecharge=true）前往平台充值算力后重试
17001200内容风控拦截调整提示词或参考图后重试
500500服务内部错误请携带 X-Request-Id 联系平台排查

算力不足（4002）时响应 data 中会包含 needRecharge、requiredCost、suggestedPackages 字段，可直接用于引导充值。

常见问题

立即在开发者中心禁用该Key并重新生成。平台仅在库中保存Key哈希，无法找回明文，轮换新Key是唯一方案。

更新日志

v1.1.02026-09-16
  • ·开放算力余额查询与消耗预估接口
  • ·按Key的QPS限流上线（HTTP 429 / 业务码4013）
  • ·开发者中心上线：应用与Key管理、用量统计、调用日志
v1.0.02026-09-16
  • ·开放图片生成、视频生成、文案生成三类核心能力
  • ·API Key 鉴权上线
  • ·文档站首次发布