NAV
cURL Ruby Python JavaScript

快速开始

一分钟内生成您的第一张 AI 图像。

1. 获取 API Key

从 API Keys 页面获取您的 API Key。所有 API 请求都需要它。

2. 生成图像

复制此命令，替换 YOUR_API_TOKEN，然后运行：

curl -X POST "https://runapi.ai/api/v1/nano_banana/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana", "prompt": "一只戴着太空头盔的可爱猫咪"}'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/nano_banana/text_to_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = { model: 'nano-banana', prompt: '一只戴着太空头盔的可爱猫咪' }.to_json

response = http.request(request)
puts response.body

import requests

response = requests.post(
    'https://runapi.ai/api/v1/nano_banana/text_to_image',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={'model': 'nano-banana', 'prompt': '一只戴着太空头盔的可爱猫咪'}
)
print(response.json())

fetch('https://runapi.ai/api/v1/nano_banana/text_to_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'nano-banana',
    prompt: '一只戴着太空头盔的可爱猫咪'
  })
})
.then(res => res.json())
.then(data => console.log(data));

响应：

{
  "id": "281e5b0f...f39b9"
}

这将创建一个图像生成任务并返回任务 ID。

3. 获取图像

使用任务 ID 检查结果：

curl "https://runapi.ai/api/v1/nano_banana/text_to_image/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

task_id = 'YOUR_TASK_ID'
uri = URI("https://runapi.ai/api/v1/nano_banana/text_to_image/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

task_id = 'YOUR_TASK_ID'
response = requests.get(
    f'https://runapi.ai/api/v1/nano_banana/text_to_image/{task_id}',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
print(response.json())

const taskId = 'YOUR_TASK_ID';

fetch(`https://runapi.ai/api/v1/nano_banana/text_to_image/${taskId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
})
.then(res => res.json())
.then(data => console.log(data));

完成时的响应：

{
  "id": "281e5b0f...f39b9",
  "status": "completed",
  "model": "nano-banana",
  "images": [
    {
      "url": "https://file.runapi.ai/generated/image1.png"
    }
  ]
}

每 5 秒轮询此端点，直到 status 为 completed（通常 10-30 秒）。images 数组包含生成图像对象。生成文件链接是临时链接，有效期为 7 天；如需长期使用，请下载并保存到你自己的持久化存储。

提示

生产环境使用 Callback：与其轮询，不如提供 callback_url 在任务完成时自动接收通知。这样更高效可靠。详见下方 Callbacks。

常见首次调用错误：

错误 原因 解决方案
401 Unauthorized API Key 无效或缺失 检查 API Key 是否正确并包含在请求头中
403 Forbidden API Key 限额已达上限或权限不足 检查该 API Key 是否有权限，且未达到消费限额
422 Unprocessable 参数无效 检查必需字段：model 和 prompt
402 Payment Required 积分不足 购买积分 或检查余额

概述

身份验证

runapi.ai 使用 API Key 来验证请求。在 Authorization 头中包含您的 API Key：

Authorization: Bearer YOUR_API_TOKEN

从 API Keys 页面获取您的 API Key。

基础 URL

大部分 API 请求（图像、视频、音乐生成）应发送到：

https://runapi.ai/api/v1

LLM 端点使用 SDK 兼容路径，确保客户端无缝接入：

SDK Base URL 端点路径
Anthropic SDK https://runapi.ai /v1/messages, /v1/models
OpenAI SDK https://runapi.ai/v1 /chat/completions, /responses, /embeddings, /models
Gemini（通过 OpenAI SDK） https://runapi.ai/v1 /chat/completions, /responses, /models

各 SDK 拼接 URL 的方式不同 — Anthropic SDK 会在 base URL 后追加 /v1/messages，而 OpenAI SDK 直接追加 /models。上述 base URL 配置确保所有请求都能正确路由，除了 URL 外无需修改任何代码。

LLM 模型目录在各 SDK surface 之间共享。Anthropic、OpenAI、Gemini、DeepSeek 的模型 ID 都会出现在兼容的 models.list() 响应中；SDK surface 只改变响应格式，不改变可见模型范围。

定价

套餐定价与 Credits 说明见 runapi.ai/pricing。当前余额与用量可在 API Keys 页面查看。

Callback

Callback 用于在任务完成时通知你的服务。请求中提供 callback_url，我们会将最终结果以 POST 请求发送到该地址。

1) 获取 Callback Secret

在账户控制台的 API Keys 中生成 Callback Secret，并保存 Base64 形式的密钥。该密钥用于校验回调签名。

2) 配置 callback_url

示例：

{
  "model": "nano-banana",
  "prompt": "宁静的山景",
  "callback_url": "https://your-app.com/callbacks/nano-banana"
}

3) 校验回调签名

每次回调会携带以下请求头：

签名算法：

示例：回调签名校验。

const crypto = require('crypto');

function verifyCallback(headers, rawBody, secret) {
  const callbackId = headers['x-callback-id'];
  const callbackTimestamp = headers['x-callback-timestamp'];
  const signatureHeader = headers['x-callback-signature'] || '';

  const signedContent = `${callbackId}.${callbackTimestamp}.${rawBody}`;
  const secretBytes = Buffer.from(secret, 'base64');
  const computedSigBase64 = crypto
    .createHmac('sha256', secretBytes)
    .update(signedContent)
    .digest('base64');

  const signatures = signatureHeader
    .split(',')
    .map(s => s.trim())
    .filter(Boolean);

  return signatures.some(expectedSig => {
    if (expectedSig.length !== computedSigBase64.length) {
      return false;
    }
    const expectedBuffer = Buffer.from(expectedSig, 'base64');
    const computedBuffer = Buffer.from(computedSigBase64, 'base64');
    return crypto.timingSafeEqual(expectedBuffer, computedBuffer);
  });
}

import base64
import hashlib
import hmac

def verify_callback(headers, raw_body, secret):
    callback_id = headers.get('X-Callback-Id')
    callback_timestamp = headers.get('X-Callback-Timestamp')
    signature_header = headers.get('X-Callback-Signature', '')

    signed_content = f"{callback_id}.{callback_timestamp}.{raw_body}"
    secret_bytes = base64.b64decode(secret)
    computed_sig_base64 = base64.b64encode(
        hmac.new(secret_bytes, signed_content.encode('utf-8'), hashlib.sha256).digest()
    ).decode('utf-8')

    signatures = [s.strip() for s in signature_header.split(',') if s.strip()]
    return any(hmac.compare_digest(sig, computed_sig_base64) for sig in signatures)

require "base64"
require "openssl"

def verify_callback(headers, raw_body, secret)
  callback_id = headers["x-callback-id"]
  callback_timestamp = headers["x-callback-timestamp"]
  signature_header = headers["x-callback-signature"].to_s

  signed_content = "#{callback_id}.#{callback_timestamp}.#{raw_body}"
  secret_bytes = Base64.decode64(secret)
  computed_sig = Base64.strict_encode64(
    OpenSSL::HMAC.digest("sha256", secret_bytes, signed_content)
  )

  signatures = signature_header.split(",").map(&:strip).reject(&:empty?)
  signatures.any? { |sig| secure_compare(sig, computed_sig) }
end

def secure_compare(a, b)
  return false unless a.bytesize == b.bytesize

  l = a.unpack("C*")
  res = 0
  b.each_byte { |byte| res |= byte ^ l.shift }
  res.zero?
end

回调内容

回调 body 与对应接口的任务查询响应一致。示例：

{
  "id": "281e5b0*********************f39b9",
  "status": "completed",
  "model": "nano-banana",
  "images": [
    {
      "url": "https://file.runapi.ai/generated/image1.png"
    }
  ]
}

回调 payload 中的生成文件链接也是临时链接，有效期为 7 天；如需长期使用，请先下载并保存到你自己的持久化存储。

重试机制

当你的端点返回非 2xx 或发生超时时，我们会最多重试 10 次，间隔逐步延长。建议快速返回 2xx，再异步处理回调内容。

SDK、CLI 与 Agent Skills

RunAPI 在 runapi-ai GitHub 组织 下发布公开 SDK、runapi CLI 与可移植 Agent Skills。

如果你不想直接调用 HTTP API，可以优先使用这些包和工具。媒体 API 返回的生成文件链接是临时链接，有效期为 7 天；应用接入时应下载并保存到自己的持久化存储。

SDK 索引

每个模型都有一个多语言 SDK 仓库，包含 JavaScript、Ruby 和 Go 源码。JavaScript 包发布在 @runapi.ai/*；Go module 位于每个 <model>-sdk/go；Ruby SDK 源码已公开，RubyGems 发布因官方注册暂停暂时延后。

ElevenLabs SDK

Flux Kontext SDK

Flux 2 SDK

GPT Image SDK

GPT Image 2 SDK

GPT-4o Image SDK

Grok Imagine SDK

Hailuo SDK

Ideogram V3 SDK

Imagen 4 SDK

Infinitalk SDK

Kling SDK

Luma SDK

Nano Banana SDK

Qwen 2 SDK

Recraft SDK

Runway SDK

Seedance SDK

Seedream SDK

Suno SDK

Topaz SDK

Veo 3 SDK

Wan SDK

Z Image SDK

RunAPI CLI

runapi 是 RunAPI 的命令行客户端 —— 一个二进制即可调用 100+ AI 模型，JSON-first 接口天然适配脚本、CI 流水线和 agent 运行时。

安装

Linux / macOS（服务器、CI、Dockerfile）：

curl -fsSL https://runapi.ai/cli/install.sh | sh

Homebrew（macOS / Linux）：

brew install runapi-ai/tap/runapi

或者把下面这段提示词发给你的 AI 代理（Claude Code、Codex、Gemini CLI、OpenClaw、Hermes）：

Install the RunAPI CLI on this machine and wire it into this agent runtime:

1. Run `curl -fsSL https://runapi.ai/cli/install.sh | sh`.
2. Save my API key with `printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -`
   (or run `runapi login` if I'm on a laptop with a browser).
3. Install the CLI skill into this runtime with `runapi agent install-skill --target <claude|codex|gemini|openclaw|hermes>`.
4. Confirm it works by running `runapi version` and `runapi auth status`.

curl 安装脚本会检测 OS/arch（Linux/macOS、amd64/arm64），从 https://runapi.ai/cli/latest.json 拉 SHA-256 校验后再写盘，遇到 musl libc（Alpine）会主动拒绝安装而不是装一个会运行时崩溃的二进制。

固定版本 / 使用镜像

# 固定到指定 tag
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --version v0.1.0

# 安装到其它目录
curl -fsSL https://runapi.ai/cli/install.sh | sh -s -- --dir ~/.local/bin

环境变量同样生效：RUNAPI_VERSION、RUNAPI_INSTALL_DIR、RUNAPI_INSTALL_BASE，以及 RUNAPI_DOWNLOAD_BASE（指向私有 CDN，从内部镜像拉 release 归档）。

Release 元数据以稳定的 JSON 契约对外发布，构建流水线无需依赖安装脚本也能自行验证下载产物：

每个 manifest 都列出 Linux 与 macOS 的 amd64/arm64 归档 URL 与 SHA-256。

无头鉴权

CLI 凭据按顺序读取 --api-key、RUNAPI_API_KEY、~/.config/runapi/config.json。RUNAPI_BASE_URL 可覆盖 API 端点。

# 推荐：通过管道传 key，避免在 `ps` / shell history 里暴露
printf '%s' "$RUNAPI_API_KEY" | runapi auth import-token --token -
runapi auth status

# 备选：在当前 shell 把 key 留在环境里
export RUNAPI_API_KEY=<your-key>
runapi auth status

auth import-token 会先用 /api/v1/me 校验后才落盘；如需绕过校验（例如离线打镜像）请加 --skip-verify。避免直接在命令行写 --token "$RUNAPI_API_KEY" —— 同主机其它用户可以通过 ps -ef 看到该值。

Agent 运行时 Skill

把对齐版本的 CLI Skill 装到受支持的 agent 运行时，让 runapi suno generate 等命令在本地有完整说明：

runapi agent install-skill --target claude
runapi agent install-skill --target codex
runapi agent install-skill --target gemini
runapi agent install-skill --target openclaw
runapi agent install-skill --target hermes
runapi agent list-targets

Skill 内容托管在 runapi-ai/cli-skill，tag 与 CLI release 保持同步。如需安装到非默认目录，使用 --target-dir <path>。

CLI 链接

Agent Skills

RunAPI Skills 是面向 Codex、Claude Code 和 Gemini CLI 的可移植指令。模型 Skill 仓库使用纯模型名；sdk-skill 安装后的 Skill 名称为 runapi-sdk，cli-skill 安装后的 Skill 名称为 runapi-cli。

Veo 3.1

Veo 3.1 在 RunAPI 上可以根据文本提示和图像创建高质量视频。支持文本生成视频、图像生成视频和基于参考图像的生成，提供质量版和快速版两种模型变体。

模型变体

模型 说明 价格 最适合
veo-3.1 最高保真度的质量模型 价格 专业内容，最高质量
veo-3.1-fast 效果强劲的快速版本 价格 快速迭代和草稿

选择生成模式

场景 模式 所需输入
纯文本描述生成视频 文本生成视频 仅文本提示
从单张图片生成动画 图像生成视频 1 张图片 + 提示
创建两张图片之间的平滑过渡 图像生成视频 2 张图片 + 提示
基于参考图片生成视频 参考图像模式 1-3 张参考图 + 提示

生成视频 (文本生成视频)

从文本提示创建视频：

curl -X POST "https://runapi.ai/api/v1/veo_3_1/text_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只狗在阳光明媚的日子里在公园玩耍，嘴里叼着球在草地上奔跑",
    "model": "veo-3.1-fast",
    "input_mode": "text",
    "aspect_ratio": "16:9",
    "duration_seconds": 8,
    "enable_translation": true,
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/veo_3_1/text_to_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  prompt: '一只狗在阳光明媚的日子里在公园玩耍，嘴里叼着球在草地上奔跑',
  model: 'veo-3.1-fast',
  input_mode: 'text',
  aspect_ratio: '16:9',
  duration_seconds: 8,
  enable_translation: true,
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/veo_3_1/text_to_video'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'prompt': '一只狗在阳光明媚的日子里在公园玩耍，嘴里叼着球在草地上奔跑',
    'model': 'veo-3.1-fast',
    'input_mode': 'text',
    'aspect_ratio': '16:9',
    'duration_seconds': 8,
    'enable_translation': True,
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  prompt: '一只狗在阳光明媚的日子里在公园玩耍，嘴里叼着球在草地上奔跑',
  model: 'veo-3.1-fast',
  input_mode: 'text',
  aspect_ratio: '16:9',
  duration_seconds: 8,
  enable_translation: true,
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/veo_3_1/text_to_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

从文本描述生成视频。

HTTP 请求

POST https://runapi.ai/api/v1/veo_3_1/text_to_video

请求参数

参数 类型 必需 说明
prompt string 是 期望视频内容的文本描述
model string 是 使用的模型：veo-3.1 (质量版) 或 veo-3.1-fast (快速版)
input_mode string 否 输入模式 (默认: text)
aspect_ratio string 否 视频宽高比: 16:9, 9:16, auto (默认: 16:9)
duration_seconds integer 否 生成视频时长：4、6 或 8 秒（默认: 8）
seeds integer 否 随机种子，用于可重现性 (10000-99999)
enable_translation boolean 否 自动将提示翻译为英文 (默认: true)
watermark string 否 可选的水印文本
callback_url string 否 完成回调的 URL

宽高比选项

响应

返回用于检查生成状态的任务 ID:

字段 类型 说明
id string 唯一任务标识符

Callback 格式

如果提供了 callback_url，生成完成时将发送 POST 请求。

成功响应: - 包含 videos 数组，含生成的视频详情 (url, resolution, has_audio) - 图像生成视频模式：包含 sources 数组，含输入图像 URL

失败响应: - 包含 error 消息，描述失败原因

成功回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://file.runapi.ai/videos/video1.mp4",
      "resolution": "720p",
      "has_audio": true
    }
  ]
}

失败回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Your prompt was flagged as violating content policies."
}

生成视频 (图像生成视频)

从一张或两张图像创建视频：

curl -X POST "https://runapi.ai/api/v1/veo_3_1/text_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "狗开始充满活力地穿过草地奔跑，欢快地跳跃",
    "first_frame_image_url": "https://cdn.runapi.ai/public/samples/image-to-video.jpg",
    "model": "veo-3.1-fast",
    "input_mode": "first_and_last_frames",
    "aspect_ratio": "16:9",
    "duration_seconds": 8,
    "enable_translation": true,
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/veo_3_1/text_to_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  prompt: '狗开始充满活力地穿过草地奔跑，欢快地跳跃',
  first_frame_image_url: 'https://cdn.runapi.ai/public/samples/image-to-video.jpg',
  model: 'veo-3.1-fast',
  input_mode: 'first_and_last_frames',
  aspect_ratio: '16:9',
  duration_seconds: 8,
  enable_translation: true,
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/veo_3_1/text_to_video'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'prompt': '狗开始充满活力地穿过草地奔跑，欢快地跳跃',
    'first_frame_image_url': 'https://cdn.runapi.ai/public/samples/image-to-video.jpg',
    'model': 'veo-3.1-fast',
    'input_mode': 'first_and_last_frames',
    'aspect_ratio': '16:9',
    'duration_seconds': 8,
    'enable_translation': True,
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  prompt: '狗开始充满活力地穿过草地奔跑，欢快地跳跃',
  first_frame_image_url: 'https://cdn.runapi.ai/public/samples/image-to-video.jpg',
  model: 'veo-3.1-fast',
  input_mode: 'first_and_last_frames',
  aspect_ratio: '16:9',
  duration_seconds: 8,
  enable_translation: true,
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/veo_3_1/text_to_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

从一张或两张图像生成视频。

HTTP 请求

POST https://runapi.ai/api/v1/veo_3_1/text_to_video

请求参数

参数 类型 必需 说明
prompt string 是 描述视频应如何动画化
first_frame_image_url string 是 首帧图像 URL
last_frame_image_url string 否 尾帧图像 URL
model string 是 使用的模型：veo-3.1 或 veo-3.1-fast
input_mode string 否 first_and_last_frames
aspect_ratio string 否 视频宽高比: 16:9, 9:16, auto (默认: 16:9)
duration_seconds integer 否 生成视频时长：4、6 或 8 秒（默认: 8）
seeds integer 否 随机种子，用于可重现性 (10000-99999)
enable_translation boolean 否 自动将提示翻译为英文 (默认: true)
watermark string 否 可选的水印文本
callback_url string 否 完成回调的 URL

帧图像

两张图像示例

{
  "prompt": "从日出到日落的平滑过渡",
  "first_frame_image_url": "https://cdn.runapi.ai/public/samples/first-frame.jpg",
  "last_frame_image_url": "https://cdn.runapi.ai/public/samples/last-frame.jpg",
  "model": "veo-3.1-fast",
  "input_mode": "first_and_last_frames",
  "aspect_ratio": "16:9"
}

Callback 格式

与文本生成视频 callback 格式相同。

生成视频 (参考图像)

使用 1-3 张参考图像创建视频：

curl -X POST "https://runapi.ai/api/v1/veo_3_1/text_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一个人在有自然光照的现代办公空间中行走",
    "reference_image_urls": [
      "https://cdn.runapi.ai/public/samples/reference-1.jpg",
      "https://cdn.runapi.ai/public/samples/reference-2.jpg",
      "https://cdn.runapi.ai/public/samples/reference-3.jpg"
    ],
    "model": "veo-3.1-fast",
    "input_mode": "reference",
    "aspect_ratio": "16:9",
    "duration_seconds": 8,
    "enable_translation": true,
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/veo_3_1/text_to_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  prompt: '一个人在有自然光照的现代办公空间中行走',
  reference_image_urls: [
    'https://cdn.runapi.ai/public/samples/reference-1.jpg',
    'https://cdn.runapi.ai/public/samples/reference-2.jpg',
    'https://cdn.runapi.ai/public/samples/reference-3.jpg'
  ],
  model: 'veo-3.1-fast',
  input_mode: 'reference',
  aspect_ratio: '16:9',
  duration_seconds: 8,
  enable_translation: true,
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/veo_3_1/text_to_video'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'prompt': '一个人在有自然光照的现代办公空间中行走',
    'reference_image_urls': [
        'https://cdn.runapi.ai/public/samples/reference-1.jpg',
        'https://cdn.runapi.ai/public/samples/reference-2.jpg',
        'https://cdn.runapi.ai/public/samples/reference-3.jpg'
    ],
    'model': 'veo-3.1-fast',
    'input_mode': 'reference',
    'aspect_ratio': '16:9',
    'duration_seconds': 8,
    'enable_translation': True,
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  prompt: '一个人在有自然光照的现代办公空间中行走',
  reference_image_urls: [
    'https://cdn.runapi.ai/public/samples/reference-1.jpg',
    'https://cdn.runapi.ai/public/samples/reference-2.jpg',
    'https://cdn.runapi.ai/public/samples/reference-3.jpg'
  ],
  model: 'veo-3.1-fast',
  input_mode: 'reference',
  aspect_ratio: '16:9',
  duration_seconds: 8,
  enable_translation: true,
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/veo_3_1/text_to_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

基于 1-3 张参考图像生成视频。

HTTP 请求

POST https://runapi.ai/api/v1/veo_3_1/text_to_video

请求参数

参数 类型 必需 说明
prompt string 是 期望视频内容的描述
reference_image_urls array 是 1-3 张参考图像 URL 的数组
model string 是 reference 输入模式必须使用 veo-3.1-fast
input_mode string 否 reference
aspect_ratio string 否 reference 输入模式必须是 16:9
duration_seconds integer 否 生成视频时长：4、6 或 8 秒（默认: 8）
seeds integer 否 随机种子，用于可重现性 (10000-99999)
enable_translation boolean 否 自动将提示翻译为英文 (默认: true)
watermark string 否 可选的水印文本
callback_url string 否 完成回调的 URL

Callback 格式

与文本生成视频 callback 格式相同。

获取视频生成状态

轮询生成结果：

curl "https://runapi.ai/api/v1/veo_3_1/text_to_video/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

require 'net/http'
require 'uri'

task_id = '550e8400-e29b-41d4-a716-446655440000'
uri = URI("https://runapi.ai/api/v1/veo_3_1/text_to_video/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

import requests

task_id = '550e8400-e29b-41d4-a716-446655440000'
url = f'https://runapi.ai/api/v1/veo_3_1/text_to_video/{task_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = '550e8400-e29b-41d4-a716-446655440000';

fetch(`https://runapi.ai/api/v1/veo_3_1/text_to_video/${taskId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

处理中：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

已完成：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://file.runapi.ai/videos/video1.mp4",
      "resolution": "1080p",
      "has_audio": true
    }
  ]
}

失败：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Video generation failed"
}

检索视频生成任务的状态和结果。

HTTP 请求

GET https://runapi.ai/api/v1/veo_3_1/text_to_video/:id

URL 参数

参数 说明
id 创建请求返回的任务 ID

响应字段

字段 类型 说明
id string 唯一任务标识符
status string 任务状态: processing, completed, failed
videos array 生成的视频对象数组 (仅完成时)
error string 错误消息 (仅失败时)

视频对象

字段 类型 说明
url string 视频下载 URL
resolution string 视频分辨率 (如 "1080p", "720p")
has_audio boolean 视频是否有音频

延伸视频

延伸现有视频：

curl -X POST "https://runapi.ai/api/v1/veo_3_1/extend_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_task_id": "550e8400-e29b-41d4-a716-446655440000",
    "prompt": "The dog continues running through the park, jumping over obstacles",
    "watermark": "MyBrand",
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/veo_3_1/extend_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  source_task_id: '550e8400-e29b-41d4-a716-446655440000',
  prompt: 'The dog continues running through the park, jumping over obstacles',
  watermark: 'MyBrand',
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/veo_3_1/extend_video'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'source_task_id': '550e8400-e29b-41d4-a716-446655440000',
    'prompt': 'The dog continues running through the park, jumping over obstacles',
    'watermark': 'MyBrand',
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  source_task_id: '550e8400-e29b-41d4-a716-446655440000',
  prompt: 'The dog continues running through the park, jumping over obstacles',
  watermark: 'MyBrand',
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/veo_3_1/extend_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

基于原始视频和文本提示延伸现有 Veo 3.1 视频，生成新的内容。

HTTP 请求

POST https://runapi.ai/api/v1/veo_3_1/extend_video

请求参数

参数 类型 必填 说明
source_task_id string 是 原始视频生成的任务 ID
prompt string 是 描述延伸内容的文本提示
seeds integer 否 随机种子，用于可重复性 (10000-99999)
watermark string 否 可选水印文字
callback_url string 否 完成回调 URL

响应

返回任务 ID，用于查询延伸状态：

字段 类型 说明
id string 唯一任务标识符

回调格式

与文本生成视频回调格式相同。

获取视频延伸状态

查询延伸结果：

curl "https://runapi.ai/api/v1/veo_3_1/extend_video/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

task_id = '550e8400-e29b-41d4-a716-446655440000'
uri = URI("https://runapi.ai/api/v1/veo_3_1/extend_video/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

task_id = '550e8400-e29b-41d4-a716-446655440000'
url = f'https://runapi.ai/api/v1/veo_3_1/extend_video/{task_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = '550e8400-e29b-41d4-a716-446655440000';

fetch(`https://runapi.ai/api/v1/veo_3_1/extend_video/${taskId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

处理中：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

已完成：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://file.runapi.ai/videos/extended_video1.mp4",
      "resolution": "720p",
      "has_audio": true
    }
  ],
  "sources": [
    {
      "url": "https://file.runapi.ai/videos/original_video1.mp4"
    }
  ]
}

失败：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Video extension failed."
}

查询视频延伸任务的状态和结果。

HTTP 请求

GET https://runapi.ai/api/v1/veo_3_1/extend_video/:id

URL 参数

参数 说明
id 创建请求返回的延伸任务 ID

响应字段

与获取视频生成状态响应格式相同。

请求 1080P 视频

请求高清 1080P 版本：

curl -X POST "https://runapi.ai/api/v1/veo_3_1/upscale_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_task_id": "550e8400-e29b-41d4-a716-446655440000",
    "output_resolution": "1080p",
    "index": 0,
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/veo_3_1/upscale_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  source_task_id: '550e8400-e29b-41d4-a716-446655440000',
  output_resolution: '1080p',
  index: 0,
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/veo_3_1/upscale_video'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'source_task_id': '550e8400-e29b-41d4-a716-446655440000',
    'output_resolution': '1080p',
    'index': 0,
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  source_task_id: '550e8400-e29b-41d4-a716-446655440000',
  output_resolution: '1080p',
  index: 0,
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/veo_3_1/upscale_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

请求已完成视频生成任务的高清 1080P 版本。

HTTP 请求

POST https://runapi.ai/api/v1/veo_3_1/upscale_video

请求参数

参数 类型 必需 说明
source_task_id string 是 已完成的视频生成任务 ID
output_resolution string 是 输出分辨率：1080p
index integer 否 如果生成了多个视频，指定视频索引 (默认: 0)
callback_url string 否 完成回调 URL

响应

返回用于检查 1080P 转换状态的任务 ID:

字段 类型 说明
id string 唯一任务标识符

Callback 格式

当 1080P 视频准备就绪时，将向您的 callback_url 发送 POST 请求。

成功响应: - 包含 status: "completed" - 包含 videos 数组，含 URL 和分辨率 - 引用 source_task_id

失败响应: - 包含 status: "failed" - 包含 error 消息，描述失败原因

成功回调示例：

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "completed",
  "source_task_id": "550e8400-e29b-41d4-a716-446655440000",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/example.mp4",
      "resolution": "1080p"
    }
  ]
}

失败回调示例：

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "failed",
  "source_task_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "Video generation failed."
}

请求 4K 视频

请求超高清 4K 版本：

curl -X POST "https://runapi.ai/api/v1/veo_3_1/upscale_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_task_id": "550e8400-e29b-41d4-a716-446655440000",
    "output_resolution": "4k",
    "index": 0,
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/veo_3_1/upscale_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  source_task_id: '550e8400-e29b-41d4-a716-446655440000',
  output_resolution: '4k',
  index: 0,
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/veo_3_1/upscale_video'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'source_task_id': '550e8400-e29b-41d4-a716-446655440000',
    'output_resolution': '4k',
    'index': 0,
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  source_task_id: '550e8400-e29b-41d4-a716-446655440000',
  output_resolution: '4k',
  index: 0,
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/veo_3_1/upscale_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

请求已完成视频生成任务的超高清 4K 版本。

HTTP 请求

POST https://runapi.ai/api/v1/veo_3_1/upscale_video

请求参数

参数 类型 必需 说明
source_task_id string 是 已完成的视频生成任务 ID
output_resolution string 是 输出分辨率：4k
index integer 否 如果生成了多个视频，指定视频索引 (默认: 0)
callback_url string 否 完成回调 URL

响应

返回用于检查 4K 转换状态的任务 ID:

字段 类型 说明
id string 唯一任务标识符

Callback 格式

当 4K 视频准备就绪时，将向您的 callback_url 发送 POST 请求。

成功响应: - 包含 status: "completed" - 包含 videos 数组，含 URL 和分辨率 - 引用 source_task_id

成功回调示例：

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "completed",
  "source_task_id": "550e8400-e29b-41d4-a716-446655440000",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/example_4k.mp4",
      "resolution": "4k"
    }
  ]
}

失败响应: - 包含 status: "failed" - 包含 error 消息，描述失败原因

失败回调示例：

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "failed",
  "source_task_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "The 4K version of this video is unavailable."
}

获取 4K 视频状态

轮询 4K 转换结果：

curl "https://runapi.ai/api/v1/veo_3_1/upscale_video/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

task_id = '3fa85f64-5717-4562-b3fc-2c963f66afa6'
uri = URI("https://runapi.ai/api/v1/veo_3_1/upscale_video/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

task_id = '3fa85f64-5717-4562-b3fc-2c963f66afa6'
url = f'https://runapi.ai/api/v1/veo_3_1/upscale_video/{task_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = '3fa85f64-5717-4562-b3fc-2c963f66afa6';

fetch(`https://runapi.ai/api/v1/veo_3_1/upscale_video/${taskId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

处理中：

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "processing",
  "source_task_id": "550e8400-e29b-41d4-a716-446655440000"
}

已完成：

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "completed",
  "source_task_id": "550e8400-e29b-41d4-a716-446655440000",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/example_4k.mp4",
      "resolution": "4k"
    }
  ]
}

失败：

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "failed",
  "source_task_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "The 4K version of this video is unavailable."
}

检查 4K 视频转换请求的状态。

HTTP 请求

GET https://runapi.ai/api/v1/veo_3_1/upscale_video/:id

URL 参数

参数 说明
id 创建请求返回的任务 ID

响应字段

字段 类型 说明
id string 唯一任务标识符
status string 任务状态: processing, completed, failed
source_task_id string 源视频生成任务 ID
videos array 视频对象数组 (仅完成时)
error string 错误消息 (仅失败时)

视频对象

字段 类型 说明
url string 4K 视频下载 URL
resolution string 视频分辨率 ("4k")

获取 1080P 视频状态

轮询 1080P 转换结果：

curl "https://runapi.ai/api/v1/veo_3_1/upscale_video/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

task_id = '3fa85f64-5717-4562-b3fc-2c963f66afa6'
uri = URI("https://runapi.ai/api/v1/veo_3_1/upscale_video/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

task_id = '3fa85f64-5717-4562-b3fc-2c963f66afa6'
url = f'https://runapi.ai/api/v1/veo_3_1/upscale_video/{task_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = '3fa85f64-5717-4562-b3fc-2c963f66afa6';

fetch(`https://runapi.ai/api/v1/veo_3_1/upscale_video/${taskId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

处理中：

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "processing",
  "source_task_id": "550e8400-e29b-41d4-a716-446655440000"
}

已完成：

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "completed",
  "source_task_id": "550e8400-e29b-41d4-a716-446655440000",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/example.mp4",
      "resolution": "1080p"
    }
  ]
}

失败：

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "failed",
  "source_task_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "Video generation failed."
}

检查 1080P 视频转换请求的状态。

HTTP 请求

GET https://runapi.ai/api/v1/veo_3_1/upscale_video/:id

URL 参数

参数 说明
id 创建请求返回的任务 ID

响应字段

字段 类型 说明
id string 唯一任务标识符
status string 任务状态: processing, completed, failed
source_task_id string 源视频生成任务 ID
videos array 视频对象数组 (仅完成时)
error string 错误消息 (仅失败时)

视频对象

字段 类型 说明
url string 1080P 视频下载 URL
resolution string 视频分辨率 ("1080p")

Seedance

Seedance 在 RunAPI 上提供视频创建模型系列。覆盖稳定的 seedance-1.5-pro，支持首尾帧与多模态参考输入的 seedance-2.0 / seedance-2.0-fast，以及轻量级、固定 5 秒 / 10 秒输出的 seedance-v1-* 系列。

模型版本

模型 说明 价格 适用场景
seedance-1.5-pro 较成熟的文生视频 / 图生视频模型，支持锁定镜头 价格 稳定生产使用
seedance-2.0 新一代模型，支持首尾帧与多模态参考输入 价格 更丰富的可控生成
seedance-2.0-fast 更快、更便宜的 2.x 版本 价格 快速迭代
seedance-v1-lite 轻量级文生视频 / 图生视频，图生视频支持可选尾帧 价格 需要精细控制的短视频
seedance-v1-pro v1 系列中画质更高的文生视频 / 图生视频 价格 v1 高画质生成
seedance-v1-pro-fast v1 图生视频专用，速度最快 价格 快速图生视频

Seedance 端点概览

任务 端点 模型
创建视频任务 创建 Seedance 文生视频任务 seedance-1.5-pro、seedance-2.0、seedance-2.0-fast、seedance-v1-lite、seedance-v1-pro、seedance-v1-pro-fast
查询视频状态 查询 Seedance 文生视频状态 -

输入模式

seedance-1.5-pro

seedance-2.0 / seedance-2.0-fast

seedance-v1-lite / seedance-v1-pro

seedance-v1-pro-fast

创建 Seedance 文生视频任务

创建一个 Seedance 视频任务：

curl -X POST "https://runapi.ai/api/v1/seedance/text_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-1.5-pro",
    "prompt": "A cinematic drone shot of a mountain lake at sunrise with mist rising from the water",
    "aspect_ratio": "16:9",
    "output_resolution": "720p",
    "duration_seconds": 8,
    "generate_audio": false,
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/seedance/text_to_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'seedance-1.5-pro',
  prompt: 'A cinematic drone shot of a mountain lake at sunrise with mist rising from the water',
  aspect_ratio: '16:9',
  output_resolution: '720p',
  duration_seconds: 8,
  generate_audio: false,
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/seedance/text_to_video'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'seedance-1.5-pro',
    'prompt': 'A cinematic drone shot of a mountain lake at sunrise with mist rising from the water',
    'aspect_ratio': '16:9',
    'output_resolution': '720p',
    'duration_seconds': 8,
    'generate_audio': False,
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'seedance-1.5-pro',
  prompt: 'A cinematic drone shot of a mountain lake at sunrise with mist rising from the water',
  aspect_ratio: '16:9',
  output_resolution: '720p',
  duration_seconds: 8,
  generate_audio: false,
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/seedance/text_to_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/seedance/text_to_video

请求参数

参数 类型 必需 说明
model string 是 seedance-1.5-pro、seedance-2.0、seedance-2.0-fast、seedance-v1-lite、seedance-v1-pro 或 seedance-v1-pro-fast
prompt string 是 视频生成提示词。seedance-1.5-pro 3–2500；seedance-2.0 / seedance-2.0-fast 3–20000；seedance-v1-* 3–10000 字符
callback_url string 否 HTTPS 回调地址
aspect_ratio string 条件必需 seedance-1.5-pro 必填；seedance-v1-lite / seedance-v1-pro 文生视频必填。2.x 支持 1:1、4:3、3:4、16:9、9:16、21:9、auto。seedance-v1-lite：1:1、4:3、3:4、16:9、9:16、9:21。seedance-v1-pro：1:1、4:3、3:4、16:9、9:16、21:9。v1 图生视频模式下不接受（由图片推导）
output_resolution string 否 seedance-1.5-pro、seedance-2.0、seedance-v1-lite、seedance-v1-pro：480p、720p、1080p。seedance-2.0-fast：480p、720p。seedance-v1-pro-fast：720p、1080p
duration_seconds integer 条件必需 seedance-1.5-pro 必填：4、8 或 12。2.x：整数 4–15。seedance-v1-*：必填，取值 5 或 10
generate_audio boolean 否 仅 1.5-pro / 2.x 支持，是否生成音频
enable_safety_checker boolean 否 内容安全检查开关
source_image_urls array 否 仅 seedance-1.5-pro 支持，最多 2 张图生视频源图
lock_camera boolean 否 锁定镜头运动。支持 seedance-1.5-pro、seedance-v1-lite、seedance-v1-pro
seed integer 否 仅 seedance-v1-lite / seedance-v1-pro 支持。随机种子，范围 [-1, 2147483647]；-1 表示随机
first_frame_image_url string 条件必需 2.x 首尾帧模式的首帧图片 URL；也会触发 v1 图生视频模式，并且 seedance-v1-pro-fast 必填
last_frame_image_url string 否 2.x 首尾帧模式，或 seedance-v1-lite 图生视频的尾帧图片 URL
reference_image_urls array 否 仅 2.x 支持，参考图片 URL（reference 模式）
reference_video_urls array 否 仅 2.x 支持，最多 3 个参考视频，总时长 ≤ 15s（reference 模式）
reference_audio_urls array 否 仅 2.x 支持，参考音频 URL；须搭配至少一张图片或一个视频（reference 模式）
web_search boolean 否 仅 2.x 支持，web search 开关

响应

字段 类型 说明
id string 唯一任务标识符
status string 初始异步状态，通常为 processing

Callback 格式

如果提供了 callback_url，任务完成时会触发 POST 回调。

成功回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/generated-video.mp4"
    }
  ]
}

失败回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Task failed"
}

查询 Seedance 文生视频状态

查询 Seedance 任务状态：

curl "https://runapi.ai/api/v1/seedance/text_to_video/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

task_id = 'YOUR_TASK_ID'
uri = URI("https://runapi.ai/api/v1/seedance/text_to_video/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

task_id = 'YOUR_TASK_ID'
response = requests.get(
    f'https://runapi.ai/api/v1/seedance/text_to_video/{task_id}',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
print(response.json())

const taskId = 'YOUR_TASK_ID';

fetch(`https://runapi.ai/api/v1/seedance/text_to_video/${taskId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
})
.then(res => res.json())
.then(data => console.log(data));

完成响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/generated-video.mp4"
    }
  ],
  "last_frame_image_url": "https://tempfile.runapi.ai/generated-last-frame.png"
}

HTTP 请求

GET https://runapi.ai/api/v1/seedance/text_to_video/:id

响应字段

字段 类型 说明
id string 任务标识符
status string processing、completed 或 failed
videos array 完成时返回生成视频 URL
last_frame_image_url string 请求并返回最后一帧图片时出现
error string 任务失败时的错误信息

Seedream

Seedream 在 RunAPI 上支持文生图和图像编辑工作流。

模型

模型 类型 价格
seedream-4.5-text-to-image 文生图 价格
seedream-4.5-edit 图像编辑 价格
seedream-5-lite-text-to-image 文生图 价格
seedream-5-lite-edit 图像编辑 价格
seedream-v4-text-to-image 文生图 价格
seedream-v4-edit 图像编辑 价格

Seedream 接口

任务 接口 方法
创建图像任务 创建 Seedream 文生图任务 POST
编辑图像任务 创建 Seedream 图像编辑任务 POST
查询文生图状态 查询 Seedream 文生图状态 GET
查询图像编辑状态 查询 Seedream 图像编辑状态 GET

创建 Seedream 文生图任务

curl -X POST "https://runapi.ai/api/v1/seedream/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5-text-to-image",
    "prompt": "雨夜霓虹街头上的旅行者电影感肖像",
    "aspect_ratio": "16:9",
    "output_quality": "basic"
  }'

POST https://runapi.ai/api/v1/seedream/text_to_image

参数 类型 必需 说明
model string 是 seedream-4.5-text-to-image、seedream-5-lite-text-to-image 或 seedream-v4-text-to-image
prompt string 是 4.5 模型支持 1-3000 字符；5-Lite 模型支持 3-3000 字符；v4 模型支持 1-5000 字符
aspect_ratio string 条件必需 4.5 和 5-Lite 文生图模型必填；1:1、4:3、3:4、16:9、9:16、2:3、3:2、21:9
output_quality string 条件必需 4.5 和 5-Lite 文生图模型必填；basic 或 high
callback_url string 否 完成后回调 URL
output_resolution string 否 仅 v4；1k、2k 或 4k；默认 1k
output_count integer 否 仅 v4；1-6 张图，默认 1
seed integer 否 仅 v4；用于复现结果的随机种子
enable_safety_checker boolean 否 可选内容安全检查开关，默认 false

Seedream v4 文生图请求

curl -X POST "https://runapi.ai/api/v1/seedream/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-v4-text-to-image",
    "prompt": "白色大理石上的玻璃茶壶产品渲染图",
    "aspect_ratio": "16:9",
    "output_resolution": "2k",
    "output_count": 3,
    "seed": 12345,
    "enable_safety_checker": true
  }'

创建 Seedream 图像编辑任务

curl -X POST "https://runapi.ai/api/v1/seedream/edit_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-v4-edit",
    "prompt": "把 logo 放到蓝色户外帽子上",
    "source_image_urls": ["https://cdn.runapi.ai/public/samples/image.jpg"],
    "aspect_ratio": "1:1",
    "output_resolution": "4k",
    "output_count": 1,
    "enable_safety_checker": false
  }'

POST https://runapi.ai/api/v1/seedream/edit_image

参数 类型 必需 说明
model string 是 seedream-4.5-edit、seedream-5-lite-edit 或 seedream-v4-edit
prompt string 是 4.5 模型支持 1-3000 字符；5-Lite 模型支持 3-3000 字符；v4 模型支持 1-5000 字符
source_image_urls array 是 源图像 URL；v4 编辑最多 10 张图
aspect_ratio string 条件必需 4.5 和 5-Lite 编辑模型必填；v4 可选；1:1、4:3、3:4、16:9、9:16、2:3、3:2、21:9
output_quality string 条件必需 4.5 和 5-Lite 编辑模型必填；basic 或 high
callback_url string 否 完成后回调 URL
output_resolution string 否 仅 v4；1k、2k 或 4k；默认 1k
output_count integer 否 仅 v4；1-6 张图，默认 1
seed integer 否 仅 v4；用于复现结果的随机种子
enable_safety_checker boolean 否 可选内容安全检查开关，默认 false

响应

{
  "id": "281e5b0f39b9",
  "status": "processing"
}

查询 Seedream 文生图状态

curl "https://runapi.ai/api/v1/seedream/text_to_image/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET https://runapi.ai/api/v1/seedream/text_to_image/:id

查询 Seedream 图像编辑状态

curl "https://runapi.ai/api/v1/seedream/edit_image/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET https://runapi.ai/api/v1/seedream/edit_image/:id

成功响应

{
  "id": "281e5b0f39b9",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/seedream/result.png"
    }
  ]
}

失败响应

{
  "id": "281e5b0f39b9",
  "status": "failed",
  "error": "Prompt rejected"
}

Runway

Runway 提供 text_to_video 和 extend_video 端点。

创建 Text To Video 任务

curl -X POST "https://runapi.ai/api/v1/runway/text_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "镜头掠过清晨海雾中的海岸线",
    "duration_seconds": 5,
    "output_resolution": "720p",
    "aspect_ratio": "16:9"
  }'

返回

{
  "id": "281e5b0f...f39b9",
  "status": "processing"
}

POST https://runapi.ai/api/v1/runway/text_to_video

价格：Runway 模型页面。

参数 类型 必填 说明
prompt string 是 视频提示词。
duration_seconds integer 是 5 或 10。
output_resolution string 是 720p 或 1080p。
first_frame_image_url string 否 图生视频首帧输入图。
aspect_ratio string 否 纯文本生成时必填。
watermark string 否 水印文本。
callback_url string 否 完成回调地址。

查询 Text To Video 任务

GET https://runapi.ai/api/v1/runway/text_to_video/{id}

完成后返回

{
  "id": "281e5b0f...f39b9",
  "status": "completed",
  "videos": [
    { "id": "video-1", "url": "https://file.runapi.ai/video.mp4" }
  ],
  "images": [
    { "url": "https://file.runapi.ai/cover.png" }
  ]
}

创建 Extend Video 任务

POST https://runapi.ai/api/v1/runway/extend_video

价格：Runway 模型页面。

参数 类型 必填 说明
source_task_id string 是 源任务 ID。
prompt string 是 如何续写视频。
output_resolution string 是 720p 或 1080p。
watermark string 否 水印文本。
callback_url string 否 完成回调地址。

查询 Extend Video 任务

GET https://runapi.ai/api/v1/runway/extend_video/{id}

Runway Aleph

Runway Aleph 提供 edit_video 端点。

创建 Edit Video 任务

POST https://runapi.ai/api/v1/runway_aleph/edit_video

curl -X POST "https://runapi.ai/api/v1/runway_aleph/edit_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Transform the scene into moody dusk lighting",
    "source_video_url": "https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerJoyrides.mp4",
    "reference_image_url": "https://raw.githubusercontent.com/github/explore/main/topics/python/python.png"
  }'
参数 类型 必填 说明
prompt string 是 转换提示词。
source_video_url string 是 源视频 URL。
reference_image_url string 否 风格参考图 URL。
aspect_ratio string 否 16:9、9:16、4:3、3:4、1:1、21:9。
seed integer 否 随机种子。
callback_url string 否 完成回调地址。

查询 Edit Video 任务

GET https://runapi.ai/api/v1/runway_aleph/edit_video/{id}

完成后返回

{
  "id": "281e5b0f...f39b9",
  "status": "completed",
  "videos": [
    { "url": "https://file.runapi.ai/runway-aleph.mp4" }
  ],
  "images": [
    { "url": "https://file.runapi.ai/runway-aleph.png" }
  ]
}

Kling

Kling 是 RunAPI 上的视频生成模型。kling-3.0 支持文生视频与图生视频，提供单镜头和多镜头两种模式，并支持用于复用主体和风格的元素引用。

模型版本

模型 说明 价格 适用场景
kling-3.0 Kling 3.0，支持单镜头与多镜头生成，并支持元素引用 价格 带场景控制的电影级视频生成
kling-ai-avatar-pro 可灵 AI 数字人 Pro，基于音频驱动的高质量数字人视频 价格 专业级数字人说话视频
kling-ai-avatar-standard 可灵 AI 数字人 Standard，基于音频驱动的高效数字人视频 价格 快速数字人说话视频
kling-ai-avatar-v1-pro 可灵 AI 数字人 v1 Pro，基于音频驱动的高质量数字人视频 价格 v1 Pro 数字人说话视频
kling-v1-avatar-standard 可灵 Avatar v1 Standard，基于音频驱动的高效数字人视频 价格 v1 Standard 数字人说话视频
kling-v2.1-pro 可灵 V2.1 Pro 图生视频，支持可选尾帧控制 价格 首尾帧控制的图生视频
kling-v2.1-standard 可灵 V2.1 Standard 图生视频，适合高效图片动画 价格 低成本图生视频草稿
kling-v2.1-master-text-to-video 可灵 V2.1 Master 文生视频，更高质量渲染 价格 高质量文生视频片段
kling-v2.1-master-image-to-video 可灵 V2.1 Master 图生视频，更高质量渲染 价格 高质量图生视频片段
kling-v2.5-turbo-text-to-video-pro 可灵 V2.5 Turbo 文生视频，高速高质量生成 价格 Turbo 加速文生视频
kling-v2.5-turbo-image-to-video-pro 可灵 V2.5 Turbo 图生视频，高速高质量生成 价格 Turbo 加速图生视频

Kling 端点概览

任务 端点 模型
创建文生视频任务 创建 Kling 文生视频任务 kling-3.0
查询文生视频状态 查询 Kling 文生视频状态 -
创建 AI 数字人任务 创建 AI 数字人 kling-ai-avatar-pro、kling-ai-avatar-standard、kling-ai-avatar-v1-pro、kling-v1-avatar-standard
查询 AI 数字人状态 查询 AI 数字人状态 -
创建 V2.1 / V2.5 视频任务 创建 V2.1 和 V2.5 视频任务 kling-v2.1-pro、kling-v2.1-standard、kling-v2.1-master-text-to-video、kling-v2.1-master-image-to-video、kling-v2.5-turbo-text-to-video-pro、kling-v2.5-turbo-image-to-video-pro
查询 V2.1 / V2.5 视频状态 查询 V2.1 和 V2.5 视频状态 -
创建动作控制任务 创建动作控制 kling-3.0
查询动作控制状态 查询动作控制状态 -

单镜头与多镜头

Kling 3.0 通过 multi_shots 字段切换两种生成模式。

单镜头模式（默认）

多镜头模式

元素引用

Kling 3.0 支持复用的“元素”——带名称的主体或风格，可以在任意提示词中通过 @element_name 语法引用。在 kling_elements 中定义每个元素，然后在 prompt 或 multi_prompt[i].prompt 中按名称引用。

在提示词中使用 @element_name 引用元素，例如："@alice 在霓虹小巷中夜行"。

使用元素引用的请求示例：

{
  "model": "kling-3.0",
  "prompt": "@alice 和 @bob 在雨中背靠背站立",
  "kling_elements": [
    {
      "name": "alice",
      "description": "一个穿红色外套、短黑发的年轻女性",
      "element_input_urls": [
        "https://cdn.runapi.ai/public/samples/portrait.jpg",
        "https://cdn.runapi.ai/public/samples/portrait.jpg"
      ]
    },
    {
      "name": "bob",
      "description": "一个穿皮大衣的高个男性",
      "element_input_urls": [
        "https://cdn.runapi.ai/public/samples/portrait-2.jpg",
        "https://cdn.runapi.ai/public/samples/portrait-2.jpg"
      ]
    }
  ]
}

创建 Kling 文生视频任务

创建单镜头 Kling 文生视频任务：

curl -X POST "https://runapi.ai/api/v1/kling/text_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "prompt": "A cinematic drone shot of a mountain lake at sunrise with mist rising from the water",
    "aspect_ratio": "16:9",
    "duration_seconds": 8,
    "output_resolution": "1080p",
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/kling/text_to_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'kling-3.0',
  prompt: 'A cinematic drone shot of a mountain lake at sunrise with mist rising from the water',
  aspect_ratio: '16:9',
  duration_seconds: 8,
  output_resolution: '1080p',
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/kling/text_to_video'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'kling-3.0',
    'prompt': 'A cinematic drone shot of a mountain lake at sunrise with mist rising from the water',
    'aspect_ratio': '16:9',
    'duration_seconds': 8,
    'output_resolution': '1080p',
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'kling-3.0',
  prompt: 'A cinematic drone shot of a mountain lake at sunrise with mist rising from the water',
  aspect_ratio: '16:9',
  duration_seconds: 8,
  output_resolution: '1080p',
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/kling/text_to_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

创建多镜头 Kling 文生视频任务：

curl -X POST "https://runapi.ai/api/v1/kling/text_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "multi_shots": true,
    "enable_sound": true,
    "aspect_ratio": "16:9",
    "output_resolution": "1080p",
    "multi_prompt": [
      { "prompt": "A lone astronaut steps out of a lunar lander onto the dusty grey surface", "duration_seconds": 4 },
      { "prompt": "Wide shot of the astronaut planting a flag as Earth rises on the horizon", "duration_seconds": 5 },
      { "prompt": "Close-up on the visor reflecting the stars and the Earth", "duration_seconds": 3 }
    ]
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/kling/text_to_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'kling-3.0',
  multi_shots: true,
  enable_sound: true,
  aspect_ratio: '16:9',
  output_resolution: '1080p',
  multi_prompt: [
    { prompt: 'A lone astronaut steps out of a lunar lander onto the dusty grey surface', duration_seconds: 4 },
    { prompt: 'Wide shot of the astronaut planting a flag as Earth rises on the horizon', duration_seconds: 5 },
    { prompt: 'Close-up on the visor reflecting the stars and the Earth', duration_seconds: 3 }
  ]
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/kling/text_to_video'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'kling-3.0',
    'multi_shots': True,
    'enable_sound': True,
    'aspect_ratio': '16:9',
    'output_resolution': '1080p',
    'multi_prompt': [
        { 'prompt': 'A lone astronaut steps out of a lunar lander onto the dusty grey surface', 'duration_seconds': 4 },
        { 'prompt': 'Wide shot of the astronaut planting a flag as Earth rises on the horizon', 'duration_seconds': 5 },
        { 'prompt': 'Close-up on the visor reflecting the stars and the Earth', 'duration_seconds': 3 }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'kling-3.0',
  multi_shots: true,
  enable_sound: true,
  aspect_ratio: '16:9',
  output_resolution: '1080p',
  multi_prompt: [
    { prompt: 'A lone astronaut steps out of a lunar lander onto the dusty grey surface', duration_seconds: 4 },
    { prompt: 'Wide shot of the astronaut planting a flag as Earth rises on the horizon', duration_seconds: 5 },
    { prompt: 'Close-up on the visor reflecting the stars and the Earth', duration_seconds: 3 }
  ]
};

fetch('https://runapi.ai/api/v1/kling/text_to_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/kling/text_to_video

请求参数

参数 类型 必需 说明
model string 是 必须为 kling-3.0
prompt string 条件必需 单镜头模式必填，描述整段视频内容的提示词
enable_sound boolean 条件必需 是否生成音频。multi_shots 为 true 时必须为 true
duration_seconds number 否 视频总时长（秒），取值范围 3 到 15
aspect_ratio string 条件必需 16:9、9:16 或 1:1。传 first_frame_image_url 时可省略（自动适配图片）
output_resolution string 否 输出分辨率：720p、1080p 或 4k
multi_shots boolean 否 设为 true 开启多镜头模式
multi_prompt array 条件必需 multi_shots 为 true 时必填。按顺序提供的 {prompt, duration_seconds} 数组，每个元素对应一个镜头
first_frame_image_url string 否 首帧图片 URL
last_frame_image_url string 否 单镜头模式的尾帧图片 URL
kling_elements array 否 用于复用主体或风格的元素引用（参见元素引用）
callback_url string 否 HTTPS 回调地址

multi_prompt 数组元素

参数 类型 必需 说明
prompt string 是 当前镜头的提示词，最长 500 字符
duration_seconds integer 是 当前镜头时长（秒），取 1 到 12 之间的整数

kling_elements 数组元素

参数 类型 必需 说明
name string 是 元素名称，可在提示词中使用 @name 引用
description string 是 元素的文字描述
element_input_urls array 否 2 到 4 张 JPG 或 PNG 图片 URL，单张尺寸不小于 300×300 像素，单张不超过 10 MB
element_input_video_urls array 否 1 个 MP4 或 MOV 视频 URL，不超过 50 MB

响应

字段 类型 说明
id string 唯一任务标识符
status string 初始异步状态，通常为 processing

Callback 格式

如果提供了 callback_url，任务完成时会触发 POST 回调。

成功回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/generated-video.mp4"
    }
  ]
}

失败回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Generation failed"
}

查询 Kling 文生视频状态

查询 Kling 任务状态：

curl "https://runapi.ai/api/v1/kling/text_to_video/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

task_id = 'YOUR_TASK_ID'
uri = URI("https://runapi.ai/api/v1/kling/text_to_video/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

task_id = 'YOUR_TASK_ID'
response = requests.get(
    f'https://runapi.ai/api/v1/kling/text_to_video/{task_id}',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
print(response.json())

const taskId = 'YOUR_TASK_ID';

fetch(`https://runapi.ai/api/v1/kling/text_to_video/${taskId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
})
.then(res => res.json())
.then(data => console.log(data));

完成响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/generated-video.mp4"
    }
  ]
}

失败响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Generation failed"
}

HTTP 请求

GET https://runapi.ai/api/v1/kling/text_to_video/:id

响应字段

字段 类型 说明
id string 任务标识符
status string processing、completed 或 failed
videos array 完成时返回生成视频 URL
error string 任务失败时的错误信息

创建 AI 数字人

基于肖像图片和音频文件生成数字人说话视频。AI 数字人功能可根据音频驱动面部动画，实现自然的唇形同步和头部动作。

创建 AI 数字人任务：

curl -X POST "https://runapi.ai/api/v1/kling/ai_avatar" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-ai-avatar-pro",
    "source_image_url": "https://cdn.runapi.ai/public/samples/portrait.jpg",
    "source_audio_url": "https://cdn.runapi.ai/public/samples/voice.mp3",
    "prompt": "一位专业主持人自信地演讲",
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/kling/ai_avatar')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer {{API_KEY}}'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'kling-ai-avatar-pro',
  source_image_url: 'https://cdn.runapi.ai/public/samples/portrait.jpg',
  source_audio_url: 'https://cdn.runapi.ai/public/samples/voice.mp3',
  prompt: '一位专业主持人自信地演讲',
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/kling/ai_avatar'
headers = {
    'Authorization': 'Bearer {{API_KEY}}',
    'Content-Type': 'application/json'
}
data = {
    'model': 'kling-ai-avatar-pro',
    'source_image_url': 'https://cdn.runapi.ai/public/samples/portrait.jpg',
    'source_audio_url': 'https://cdn.runapi.ai/public/samples/voice.mp3',
    'prompt': '一位专业主持人自信地演讲',
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'kling-ai-avatar-pro',
  source_image_url: 'https://cdn.runapi.ai/public/samples/portrait.jpg',
  source_audio_url: 'https://cdn.runapi.ai/public/samples/voice.mp3',
  prompt: '一位专业主持人自信地演讲',
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/kling/ai_avatar', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{API_KEY}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/kling/ai_avatar

请求参数

参数 类型 必需 说明
model string 是 kling-ai-avatar-pro、kling-ai-avatar-standard、kling-ai-avatar-v1-pro 或 kling-v1-avatar-standard
source_image_url string 是 肖像图片 URL。支持格式：JPEG 或 PNG，最大 10 MB
source_audio_url string 是 音频文件 URL。支持格式：MP3、WAV、AAC、MP4、OGG，最大 10 MB
prompt string 是 用于引导数字人动画的文本提示词。可为空，最长 5000 字符
callback_url string 否 HTTPS 回调地址

响应

字段 类型 说明
id string 唯一任务标识符
status string 初始异步状态，通常为 processing

Callback 格式

如果提供了 callback_url，任务完成时会触发 POST 回调。

成功回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/avatar-video.mp4"
    }
  ]
}

失败回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Generation failed"
}

查询 AI 数字人状态

查询 AI 数字人任务状态：

curl "https://runapi.ai/api/v1/kling/ai_avatar/YOUR_TASK_ID" \
  -H "Authorization: Bearer {{API_KEY}}"

task_id = 'YOUR_TASK_ID'
uri = URI("https://runapi.ai/api/v1/kling/ai_avatar/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer {{API_KEY}}'

response = http.request(request)
puts response.body

task_id = 'YOUR_TASK_ID'
response = requests.get(
    f'https://runapi.ai/api/v1/kling/ai_avatar/{task_id}',
    headers={'Authorization': 'Bearer {{API_KEY}}'}
)
print(response.json())

const taskId = 'YOUR_TASK_ID';

fetch(`https://runapi.ai/api/v1/kling/ai_avatar/${taskId}`, {
  headers: { 'Authorization': 'Bearer {{API_KEY}}' }
})
.then(res => res.json())
.then(data => console.log(data));

完成响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/avatar-video.mp4"
    }
  ]
}

失败响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Generation failed"
}

HTTP 请求

GET https://runapi.ai/api/v1/kling/ai_avatar/:id

响应字段

字段 类型 说明
id string 任务标识符
status string processing、completed 或 failed
videos array 完成时返回生成视频 URL
error string 任务失败时的错误信息

创建 V2.1 和 V2.5 视频任务

使用可灵 V2.1 和 V2.5 模型生成视频。V2.1 Master 支持文生视频和图生视频，V2.1 Pro/Standard 支持图生视频，V2.5 Turbo 提供更快的文生视频和图生视频。

创建 V2.1 Master 文生视频任务：

curl -X POST "https://runapi.ai/api/v1/kling/text_to_video" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v2.1-master-text-to-video",
    "prompt": "夕阳下的发光城市上空，一队伞兵穿过云层",
    "duration_seconds": 5,
    "aspect_ratio": "16:9",
    "negative_prompt": "blur, distorted hands",
    "cfg_scale": 0.5,
    "callback_url": "https://your-domain.com/api/callback"
  }'

创建带尾帧控制的 V2.1 Pro 图生视频任务：

curl -X POST "https://runapi.ai/api/v1/kling/image_to_video" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v2.1-pro",
    "prompt": "镜头向前推进，主体转向温暖阳光",
    "first_frame_image_url": "https://cdn.runapi.ai/public/samples/first-frame.jpg",
    "last_frame_image_url": "https://cdn.runapi.ai/public/samples/last-frame.jpg",
    "duration_seconds": 5,
    "cfg_scale": 0.5,
    "callback_url": "https://your-domain.com/api/callback"
  }'

创建 V2.1 Master 图生视频任务：

curl -X POST "https://runapi.ai/api/v1/kling/image_to_video" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v2.1-master-image-to-video",
    "prompt": "宁静风景动起来，流水流动，云朵缓慢漂移",
    "first_frame_image_url": "https://cdn.runapi.ai/public/samples/image-to-video.jpg",
    "duration_seconds": 5,
    "cfg_scale": 0.5,
    "callback_url": "https://your-domain.com/api/callback"
  }'

创建 V2.5 Turbo 文生视频任务：

curl -X POST "https://runapi.ai/api/v1/kling/text_to_video" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v2.5-turbo-text-to-video-pro",
    "prompt": "一只金毛犬在野花丛中慢动作奔跑",
    "duration_seconds": 5,
    "aspect_ratio": "16:9",
    "cfg_scale": 0.5,
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/kling/text_to_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer {{API_KEY}}'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'kling-v2.5-turbo-text-to-video-pro',
  prompt: '一只金毛犬在野花丛中慢动作奔跑',
  duration_seconds: 5,
  aspect_ratio: '16:9',
  cfg_scale: 0.5,
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/kling/text_to_video'
headers = {
    'Authorization': 'Bearer {{API_KEY}}',
    'Content-Type': 'application/json'
}
data = {
    'model': 'kling-v2.5-turbo-text-to-video-pro',
    'prompt': '一只金毛犬在野花丛中慢动作奔跑',
    'duration_seconds': 5,
    'aspect_ratio': '16:9',
    'cfg_scale': 0.5,
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'kling-v2.5-turbo-text-to-video-pro',
  prompt: '一只金毛犬在野花丛中慢动作奔跑',
  duration_seconds: 5,
  aspect_ratio: '16:9',
  cfg_scale: 0.5,
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/kling/text_to_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{API_KEY}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

创建 V2.5 Turbo 图生视频任务：

curl -X POST "https://runapi.ai/api/v1/kling/image_to_video" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v2.5-turbo-image-to-video-pro",
    "prompt": "画面活了起来，微风吹过，树木摇曳",
    "first_frame_image_url": "https://cdn.runapi.ai/public/samples/image-to-video.jpg",
    "duration_seconds": 5,
    "aspect_ratio": "16:9",
    "cfg_scale": 0.5,
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/kling/image_to_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer {{API_KEY}}'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'kling-v2.5-turbo-image-to-video-pro',
  prompt: '画面活了起来，微风吹过，树木摇曳',
  first_frame_image_url: 'https://cdn.runapi.ai/public/samples/image-to-video.jpg',
  duration_seconds: 5,
  aspect_ratio: '16:9',
  cfg_scale: 0.5,
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/kling/image_to_video'
headers = {
    'Authorization': 'Bearer {{API_KEY}}',
    'Content-Type': 'application/json'
}
data = {
    'model': 'kling-v2.5-turbo-image-to-video-pro',
    'prompt': '画面活了起来，微风吹过，树木摇曳',
    'first_frame_image_url': 'https://cdn.runapi.ai/public/samples/image-to-video.jpg',
    'duration_seconds': 5,
    'aspect_ratio': '16:9',
    'cfg_scale': 0.5,
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'kling-v2.5-turbo-image-to-video-pro',
  prompt: '画面活了起来，微风吹过，树木摇曳',
  first_frame_image_url: 'https://cdn.runapi.ai/public/samples/image-to-video.jpg',
  duration_seconds: 5,
  aspect_ratio: '16:9',
  cfg_scale: 0.5,
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/kling/image_to_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{API_KEY}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/kling/image_to_video

请求参数（文生视频）

参数 类型 必需 说明
model string 是 kling-v2.1-master-text-to-video 或 kling-v2.5-turbo-text-to-video-pro
prompt string 是 描述视频内容的提示词，V2.1 Master 最长 5000 字符，V2.5 Turbo 最长 2500 字符
duration_seconds number 否 视频时长（秒）：5 或 10，默认 5
aspect_ratio string 否 16:9、9:16 或 1:1
negative_prompt string 否 希望在生成视频中避免的内容，V2.1 Master 最长 500 字符，V2.5 Turbo 最长 2500 字符
cfg_scale number 否 创意自由度与提示词遵循程度的平衡，取值 0 到 1
callback_url string 否 HTTPS 回调地址

请求参数（图生视频）

参数 类型 必需 说明
model string 是 kling-v2.1-pro、kling-v2.1-standard、kling-v2.1-master-image-to-video 或 kling-v2.5-turbo-image-to-video-pro
prompt string 是 描述视频内容的提示词，V2.1 最长 5000 字符，V2.5 Turbo 最长 2500 字符
first_frame_image_url string 是 作为动画来源的图片 URL
last_frame_image_url string 否 尾帧图片 URL，kling-v2.5-turbo-image-to-video-pro 和 kling-v2.1-pro 支持
duration_seconds number 否 视频时长：5 或 10，默认 5
aspect_ratio string 否 16:9、9:16 或 1:1
negative_prompt string 否 希望在生成视频中避免的内容，最长 500 字符
cfg_scale number 否 创意自由度与提示词遵循程度的平衡，取值 0 到 1
callback_url string 否 HTTPS 回调地址

响应

字段 类型 说明
id string 唯一任务标识符
status string 初始异步状态，通常为 processing

Callback 格式

如果提供了 callback_url，任务完成时会触发 POST 回调。

成功回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/turbo-video.mp4"
    }
  ]
}

失败回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Generation failed"
}

查询 V2.1 和 V2.5 视频状态

查询 V2.1 或 V2.5 任务状态：

curl "https://runapi.ai/api/v1/kling/image_to_video/YOUR_TASK_ID" \
  -H "Authorization: Bearer {{API_KEY}}"

task_id = 'YOUR_TASK_ID'
uri = URI("https://runapi.ai/api/v1/kling/image_to_video/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer {{API_KEY}}'

response = http.request(request)
puts response.body

task_id = 'YOUR_TASK_ID'
response = requests.get(
    f'https://runapi.ai/api/v1/kling/image_to_video/{task_id}',
    headers={'Authorization': 'Bearer {{API_KEY}}'}
)
print(response.json())

const taskId = 'YOUR_TASK_ID';

fetch(`https://runapi.ai/api/v1/kling/image_to_video/${taskId}`, {
  headers: { 'Authorization': 'Bearer {{API_KEY}}' }
})
.then(res => res.json())
.then(data => console.log(data));

完成响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/turbo-video.mp4"
    }
  ]
}

失败响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Generation failed"
}

HTTP 请求

GET https://runapi.ai/api/v1/kling/image_to_video/:id

响应字段

字段 类型 说明
id string 任务标识符
status string processing、completed 或 failed
videos array 完成时返回生成视频 URL
error string 任务失败时的错误信息

创建动作控制

将参考视频中的动作迁移到主体图片上。动作控制功能从视频中提取运动模式，并应用到静态图片上，生成一段主体按照参考视频动作运动的新视频。

创建动作控制任务：

curl -X POST "https://runapi.ai/api/v1/kling/motion_control" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "source_first_frame_image_url": "https://cdn.runapi.ai/public/samples/image.jpg",
    "reference_video_url": "https://cdn.runapi.ai/public/samples/video.mp4",
    "prompt": "一个人在工作室优雅地跳舞",
    "output_resolution": "1080p",
    "character_orientation": "video",
    "background_source": "video",
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/kling/motion_control')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer {{API_KEY}}'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'kling-3.0',
  source_first_frame_image_url: 'https://cdn.runapi.ai/public/samples/image.jpg',
  reference_video_url: 'https://cdn.runapi.ai/public/samples/video.mp4',
  prompt: '一个人在工作室优雅地跳舞',
  output_resolution: '1080p',
  character_orientation: 'video',
  background_source: 'video',
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/kling/motion_control'
headers = {
    'Authorization': 'Bearer {{API_KEY}}',
    'Content-Type': 'application/json'
}
data = {
    'model': 'kling-3.0',
    'source_first_frame_image_url': 'https://cdn.runapi.ai/public/samples/image.jpg',
    'reference_video_url': 'https://cdn.runapi.ai/public/samples/video.mp4',
    'prompt': '一个人在工作室优雅地跳舞',
    'output_resolution': '1080p',
    'character_orientation': 'video',
    'background_source': 'video',
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'kling-3.0',
  source_first_frame_image_url: 'https://cdn.runapi.ai/public/samples/image.jpg',
  reference_video_url: 'https://cdn.runapi.ai/public/samples/video.mp4',
  prompt: '一个人在工作室优雅地跳舞',
  output_resolution: '1080p',
  character_orientation: 'video',
  background_source: 'video',
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/kling/motion_control', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{API_KEY}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/kling/motion_control

请求参数

参数 类型 必需 说明
model string 是 必须为 kling-3.0
source_first_frame_image_url string 是 主体图片 URL
reference_video_url string 是 参考动作视频 URL
prompt string 否 用于引导生成的文本提示词，最长 2500 字符
output_resolution string 否 输出分辨率：720p 或 1080p
character_orientation string 否 决定角色朝向的来源：video 或 image
background_source string 否 提供背景的来源：video 或 image
callback_url string 否 HTTPS 回调地址

响应

字段 类型 说明
id string 唯一任务标识符
status string 初始异步状态，通常为 processing

Callback 格式

如果提供了 callback_url，任务完成时会触发 POST 回调。

成功回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/motion-control-video.mp4"
    }
  ]
}

失败回调示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Generation failed"
}

查询动作控制状态

查询动作控制任务状态：

curl "https://runapi.ai/api/v1/kling/motion_control/YOUR_TASK_ID" \
  -H "Authorization: Bearer {{API_KEY}}"

task_id = 'YOUR_TASK_ID'
uri = URI("https://runapi.ai/api/v1/kling/motion_control/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer {{API_KEY}}'

response = http.request(request)
puts response.body

task_id = 'YOUR_TASK_ID'
response = requests.get(
    f'https://runapi.ai/api/v1/kling/motion_control/{task_id}',
    headers={'Authorization': 'Bearer {{API_KEY}}'}
)
print(response.json())

const taskId = 'YOUR_TASK_ID';

fetch(`https://runapi.ai/api/v1/kling/motion_control/${taskId}`, {
  headers: { 'Authorization': 'Bearer {{API_KEY}}' }
})
.then(res => res.json())
.then(data => console.log(data));

完成响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/motion-control-video.mp4"
    }
  ]
}

失败响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Generation failed"
}

HTTP 请求

GET https://runapi.ai/api/v1/kling/motion_control/:id

响应字段

字段 类型 说明
id string 任务标识符
status string processing、completed 或 failed
videos array 完成时返回生成视频 URL
error string 任务失败时的错误信息

Suno

Suno API 提供全面的音乐生成和处理功能。

基础端点： https://runapi.ai/api/v1/suno

Suno 端点概览

分类 端点 用途
核心 生成音乐, 生成歌词 从零创建音乐或歌词
扩展编辑 扩展音乐, 替换片段 修改现有曲目
音频叠加 添加人声, 添加伴奏 叠加人声或伴奏
音频分离 人声分离, MIDI 生成 分离音频组件
视觉内容 音乐封面, 音乐视频 生成封面或视频
音频变换 Upload and Covers, Upload and Extensions, Mashup 处理您的音频文件
音效设计 生成音效 环境音、循环音效、音效素材
声音 生成验证短语, 重新生成验证短语, 生成自定义声音, 检查自定义声音 准备声音校验短语和可复用自定义声音

模型版本

模型 说明
suno-v5 卓越音乐表达、更快生成，最长 8 分钟
suno-v4.5-plus 更丰富音质、新创作方式，最长 8 分钟
suno-v4.5-all 智能提示、更快生成，最长 8 分钟
suno-v4.5 智能提示、快速生成，最长 8 分钟
suno-v4 改进人声质量，最长 4 分钟

通用参数

以下参数在大多数生成端点中通用：

参数 类型 说明
model string 模型版本 (suno-v5, suno-v4.5-plus, suno-v4.5-all, suno-v4.5, suno-v4)
callback_url string 完成通知 URL
style_weight number 风格坚持度 (0-1，越高越严格)
weirdness_constraint number 创意度 (0-1，越高越实验性)
audio_weight number 音频一致性 (0-1，越高越一致)
vocal_gender string 人声偏好：male（男）或 female（女）。适用于歌词、风格/标题或纯音乐控制，仅增加概率。

通用错误代码

状态码 错误信息 说明
400 SENSITIVE_WORD_ERROR 提示词包含敏感词。请修改提示词后重试。
402 INSUFFICIENT_QUOTA 账户余额不足。请充值。
408 TIMEOUT 任务超时。请稍后重试。
429 RATE_LIMIT_EXCEEDED 请求过多。请稍后重试。
500 SERVER_ERROR 内部服务器错误。请稍后重试。
531 REFUNDED 任务失败，已自动退款。请重试。

生成音乐

创建音乐生成任务：

curl -X POST "https://runapi.ai/api/v1/suno/text_to_music" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vocal_mode": "auto_lyrics",
    "prompt": "A chill lo-fi beat with soft vocals",
    "model": "suno-v5",
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

require 'net/http'
require 'json'

uri = URI('https://runapi.ai/api/v1/suno/text_to_music')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  vocal_mode: "auto_lyrics",
  prompt: "A chill lo-fi beat with soft vocals",
  model: "suno-v5",
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

response = http.request(request)

import requests

url = "https://runapi.ai/api/v1/suno/text_to_music"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "vocal_mode": "auto_lyrics",
    "prompt": "A chill lo-fi beat with soft vocals",
    "model": "suno-v5",
    "callback_url": "https://your-app.com/callbacks/suno"
}

response = requests.post(url, headers=headers, json=data)

fetch('https://runapi.ai/api/v1/suno/text_to_music', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    vocal_mode: "auto_lyrics",
    prompt: "A chill lo-fi beat with soft vocals",
    model: "suno-v5",
    callback_url: "https://your-app.com/callbacks/suno"
  })
});

从文本描述生成原创音乐。

HTTP 请求

POST https://runapi.ai/api/v1/suno/text_to_music

请求体参数

请求形态

选择 vocal_mode。每个请求都需要 model，也可以提供 callback_url。

参数 类型 必填 说明
vocal_mode string 是 auto_lyrics、exact_lyrics 或 instrumental。
prompt string 否 歌曲 brief，用于自动生成歌词。
lyrics string 否 精确演唱歌词。
style string 否 音乐风格。
title string 否 音乐标题。
model string 是 模型版本：suno-v5、suno-v4.5-plus、suno-v4.5-all、suno-v4.5、suno-v4
callback_url string 否 接收完成通知的 URL
persona_id string 否 要应用的角色 ID。通过生成角色创建。
persona_type string 否 角色类型，配合 persona_id 使用。可选值：style 应用风格特征，voice 应用声音特征（仅 suno-v5）。无 persona_id 时忽略。
negative_tags string 否 要排除的音乐风格
vocal_gender string 否 人声偏好：male（男）或 female（女）。仅增加概率。
style_weight number 否 风格坚持权重（0-1，建议两位小数）
weirdness_constraint number 否 创意/新颖性约束（0-1，建议两位小数）
audio_weight number 否 音频一致性权重（0-1，建议两位小数）

响应

返回用于跟踪生成状态的任务 ID。

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

如果提供了 callback_url，系统将在生成过程中的多个阶段发送 POST 请求：

生成阶段： - text_generated：所有文本内容就绪（标题、歌词、标签等） - first_audio_ready：第一条音轨完成 - all_audios_ready：所有音频完成 - failed：生成失败

成功响应： - 包含 audios 数组和生成的音乐 URL - 包含音轨详情，如标题、标签、时长 - 每个音轨包含 audio_url、stream_audio_url 和 image_url

失败响应： - 包含描述失败原因的 error 消息

成功回调示例：

{
  "id": "task-id",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "audio-id-1",
      "audio_url": "https://file.runapi.ai/audio1.mp3",
      "stream_audio_url": "https://file.runapi.ai/stream1",
      "image_url": "https://file.runapi.ai/cover1.jpg",
      "lyrics": "[Verse] Lyrics...",
      "model_name": "chirp-v3-5",
      "title": "Song Title",
      "tags": ["genre1", "genre2"],
      "duration": 198.44
    }
  ]
}

失败回调示例：

{
  "id": "task-id",
  "status": "failed",
  "generation_stage": "failed",
  "error": "Error message"
}

获取音乐生成详情

查询音乐生成状态：

curl "https://runapi.ai/api/v1/suno/text_to_music/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/text_to_music/TASK_ID')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)

url = "https://runapi.ai/api/v1/suno/text_to_music/TASK_ID"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/text_to_music/TASK_ID', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
});

获取音乐生成任务的详细信息。

HTTP 请求

GET https://runapi.ai/api/v1/suno/text_to_music/:id

URL 参数

参数 说明
id 从生成端点返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing",
  "generation_stage": "text_generated"
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] 夜晚城市 灯火辉煌",
      "model_name": "chirp-v3-5",
      "title": "钢铁侠",
      "tags": ["electrifying", "rock"],
      "duration": 198.44
    }
  ]
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "generation_stage": "failed",
  "error": "Generation failed"
}

扩展音乐

扩展已有音乐：

curl -X POST "https://runapi.ai/api/v1/suno/extend_music" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter_mode": "custom",
    "audio_id": "2902e564-9001-427c-a6fa-585b86a864fe",
    "prompt": "Extend the music with more relaxing notes",
    "style": "Classical",
    "title": "Peaceful Piano Extended",
    "continue_at": 60,
    "model": "suno-v4",
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  parameter_mode: "custom",
  audio_id: "2902e564-9001-427c-a6fa-585b86a864fe",
  prompt: "Extend the music with more relaxing notes",
  style: "Classical",
  title: "Peaceful Piano Extended",
  continue_at: 60,
  model: "suno-v4",
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "parameter_mode": "custom",
    "audio_id": "2902e564-9001-427c-a6fa-585b86a864fe",
    "prompt": "Extend the music with more relaxing notes",
    "style": "Classical",
    "title": "Peaceful Piano Extended",
    "continue_at": 60,
    "model": "suno-v4",
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  parameter_mode: "custom",
  audio_id: "2902e564-9001-427c-a6fa-585b86a864fe",
  prompt: "Extend the music with more relaxing notes",
  style: "Classical",
  title: "Peaceful Piano Extended",
  continue_at: 60,
  model: "suno-v4",
  callback_url: "https://your-app.com/callbacks/suno"
})

扩展或修改现有音乐曲目，同时保持原始风格。

HTTP 请求

POST https://runapi.ai/api/v1/suno/extend_music

请求体参数

参数 类型 必填 说明
parameter_mode string 是 source 继承源音频参数，或 custom 使用本次请求参数
audio_id string 是 要扩展的音轨 ID
callback_url string 否 接收任务完成通知的 URL
model string 是 模型版本：suno-v5、suno-v4.5-plus、suno-v4.5-all、suno-v4.5、suno-v4
prompt string 条件 如何扩展的描述（当 parameter_mode 为 custom 时必填）
style string 条件 音乐风格（当 parameter_mode 为 custom 时必填）
title string 条件 音乐标题（当 parameter_mode 为 custom 时必填）
continue_at number 条件 开始时间（秒）（当 parameter_mode 为 custom 时必填）
persona_id string 否 当 parameter_mode 为 custom 时要应用的角色 ID。通过生成角色创建。
persona_type string 否 角色类型，配合 persona_id 使用。可选值：style 应用风格特征，voice 应用声音特征（仅 suno-v5）。无 persona_id 时忽略。
negative_tags string 否 要排除的音乐风格
vocal_gender string 否 首选人声性别：male（男）或 female（女）。仅在 parameter_mode: "custom" 时生效。仅增加概率。
style_weight number 否 风格坚持权重（0-1）
weirdness_constraint number 否 创意约束（0-1）
audio_weight number 否 音频一致性权重（0-1）

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

如果提供了 callback_url，系统将在多个阶段发送 POST 请求。

成功响应： - 包含扩展后的音轨 URL - 包含元数据，如标题、标签、时长 - 扩展后的音轨保持与源音频的风格一致

成功回调示例：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] Night city lights shining bright",
      "model_name": "chirp-v3-5",
      "title": "Iron Man Extended",
      "tags": ["electrifying", "rock"],
      "duration": 278.44
    }
  ]
}

失败回调示例：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "generation_stage": "failed",
  "error": "Failed to extend music, invalid audio source"
}

获取音乐扩展详情

查询音乐扩展状态：

curl "https://runapi.ai/api/v1/suno/extend_music/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/extend_music/TASK_ID')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

url = "https://runapi.ai/api/v1/suno/extend_music/TASK_ID"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/extend_music/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询音乐扩展任务的状态和详情。

HTTP 请求

GET https://runapi.ai/api/v1/suno/extend_music/:id

URL 参数

参数 说明
id 提交扩展请求时返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] Night city lights shining bright",
      "model_name": "chirp-v3-5",
      "title": "Iron Man Extended",
      "tags": ["electrifying", "rock"],
      "duration": 278.44
    }
  ]
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Extension generation failed."
}

生成歌词

生成歌词：

curl -X POST "https://runapi.ai/api/v1/suno/generate_lyrics" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A song about peaceful night in the city",
    "callback_url": "https://your-app.com/callbacks/suno-lyrics"
  }'

request.body = {
  prompt: "A song about peaceful night in the city",
  callback_url: "https://your-app.com/callbacks/suno-lyrics"
}.to_json

data = {
    "prompt": "A song about peaceful night in the city",
    "callback_url": "https://your-app.com/callbacks/suno-lyrics"
}

body: JSON.stringify({
  prompt: "A song about peaceful night in the city",
  callback_url: "https://your-app.com/callbacks/suno-lyrics"
})

基于文本提示生成创意歌词内容。

HTTP 请求

POST https://runapi.ai/api/v1/suno/generate_lyrics

请求体参数

参数 类型 必填 说明
prompt string 是 所需歌词的主题、风格或主题。最多 200 字符
callback_url string 否 接收完成回调的公开可访问 URL

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

当歌词生成任务完成时，系统将向您的 callback_url 发送 POST 请求。

成功响应： - 包含 lyrics 数组和生成的内容 - 包含标题和结构化文本 - 返回一个或多个歌词条目，包含主歌/副歌等段落

成功回调示例：

{
  "id": "277a0b89-cd57-455e-ba43-7c6532ca99ed",
  "status": "completed",
  "lyrics": [
    {
      "title": "Starry Night Dreams",
      "text": "[Verse]\nMoonlight spreads across the windowsill..."
    }
  ]
}

失败回调示例：

{
  "id": "277a0b89-cd57-455e-ba43-7c6532ca99ed",
  "status": "failed",
  "error": "Song Description flagged for moderation"
}

获取歌词生成详情

查询歌词生成状态：

curl "https://runapi.ai/api/v1/suno/generate_lyrics/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/generate_lyrics/TASK_ID')
request = Net::HTTP::Get.new(uri)

url = "https://runapi.ai/api/v1/suno/generate_lyrics/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/generate_lyrics/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

检索歌词生成任务的状态。

HTTP 请求

GET https://runapi.ai/api/v1/suno/generate_lyrics/:id

URL 参数

参数 说明
id 从 POST /lyrics 返回的任务 ID

响应

处理中：

{
  "id": "277a0b89-cd57-455e-ba43-7c6532ca99ed",
  "status": "processing",
  "lyrics": []
}

已完成：

{
  "id": "277a0b89-cd57-455e-ba43-7c6532ca99ed",
  "status": "completed",
  "lyrics": [
    {
      "title": "Starry Night Dreams",
      "text": "[Verse]\nMoonlight spreads across the windowsill..."
    }
  ]
}

失败：

{
  "id": "277a0b89-cd57-455e-ba43-7c6532ca99ed",
  "status": "failed",
  "error": "Lyrics generation failed.",
  "lyrics": []
}

添加人声

添加人声：

curl -X POST "https://runapi.ai/api/v1/suno/add_vocals" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_url": "https://cdn.runapi.ai/public/samples/music.mp3",
    "lyrics": "[Verse]\nA calm and relaxing piano track with soothing vocals",
    "title": "Relaxing Piano with Vocals",
    "style": "Jazz",
    "model": "suno-v4.5-plus",
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  upload_url: "https://cdn.runapi.ai/public/samples/music.mp3",
  lyrics: "[Verse]\nA calm and relaxing piano track with soothing vocals",
  title: "Relaxing Piano with Vocals",
  style: "Jazz",
  model: "suno-v4.5-plus",
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "upload_url": "https://cdn.runapi.ai/public/samples/music.mp3",
    "lyrics": "[Verse]\nA calm and relaxing piano track with soothing vocals",
    "title": "Relaxing Piano with Vocals",
    "style": "Jazz",
    "model": "suno-v4.5-plus",
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  upload_url: "https://cdn.runapi.ai/public/samples/music.mp3",
  lyrics: "[Verse]\nA calm and relaxing piano track with soothing vocals",
  title: "Relaxing Piano with Vocals",
  style: "Jazz",
  model: "suno-v4.5-plus",
  callback_url: "https://your-app.com/callbacks/suno"
})

为上传的音频文件添加人声。

HTTP 请求

POST https://runapi.ai/api/v1/suno/add_vocals

请求体参数

参数 类型 必填 说明
upload_url string 是 上传的音乐文件 URL。可使用 POST /api/v1/files 返回的 url；该临时链接有效期为 1 小时。
lyrics string 是 精确演唱歌词
title string 是 音乐曲目的标题
style string 是 音乐风格/流派
model string 是 模型版本：suno-v5、suno-v4.5-plus、suno-v4.5-all、suno-v4.5、suno-v4
callback_url string 否 接收完成通知的 URL
negative_tags string 否 要排除的风格
vocal_gender string 否 首选人声性别：male（男）或 female（女）。仅增加概率。
style_weight number 否 风格坚持权重（0-1）
weirdness_constraint number 否 创意约束（0-1）
audio_weight number 否 音频一致性权重（0-1）

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

系统将在多个阶段向您的 callback_url 发送 POST 请求。

成功回调示例：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/audio.mp3",
      "stream_audio_url": "https://file.runapi.ai/stream",
      "image_url": "https://file.runapi.ai/cover.jpg",
      "lyrics": "[Verse] Soothing melody with calm vocals",
      "model_name": "chirp-v4-5",
      "title": "Relaxing Piano with Vocals",
      "tags": ["jazz", "calm", "soothing"],
      "duration": 182.32
    }
  ]
}

失败回调示例：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "generation_stage": "failed",
  "error": "Vocal generation failed."
}

获取添加人声详情

查询添加人声状态：

curl "https://runapi.ai/api/v1/suno/add_vocals/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/add_vocals/TASK_ID')
request = Net::HTTP::Get.new(uri)

url = "https://runapi.ai/api/v1/suno/add_vocals/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/add_vocals/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

获取添加人声任务的详细信息。

HTTP 请求

GET https://runapi.ai/api/v1/suno/add_vocals/:id

URL 参数

参数 说明
id 从添加人声端点返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] Soothing melody with calm vocals",
      "model_name": "chirp-v4-5",
      "title": "Relaxing Piano with Vocals",
      "tags": ["jazz", "calm", "soothing"],
      "duration": 182.32
    }
  ]
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Vocal generation failed."
}

添加伴奏

添加伴奏：

curl -X POST "https://runapi.ai/api/v1/suno/add_instrumental" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_url": "https://cdn.runapi.ai/public/samples/music.mp3",
    "title": "Relaxing Piano",
    "tags": "Relaxing Piano, Ambient, Peaceful",
    "negative_tags": "Heavy Metal, Aggressive Drums",
    "model": "suno-v4.5-plus",
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  upload_url: "https://cdn.runapi.ai/public/samples/music.mp3",
  title: "Relaxing Piano",
  tags: "Relaxing Piano, Ambient, Peaceful",
  negative_tags: "Heavy Metal, Aggressive Drums",
  model: "suno-v4.5-plus",
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "upload_url": "https://cdn.runapi.ai/public/samples/music.mp3",
    "title": "Relaxing Piano",
    "tags": "Relaxing Piano, Ambient, Peaceful",
    "negative_tags": "Heavy Metal, Aggressive Drums",
    "model": "suno-v4.5-plus",
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  upload_url: "https://cdn.runapi.ai/public/samples/music.mp3",
  title: "Relaxing Piano",
  tags: "Relaxing Piano, Ambient, Peaceful",
  negative_tags: "Heavy Metal, Aggressive Drums",
  model: "suno-v4.5-plus",
  callback_url: "https://your-app.com/callbacks/suno"
})

为上传的音频文件生成量身定制的音乐伴奏。

HTTP 请求

POST https://runapi.ai/api/v1/suno/add_instrumental

请求体参数

参数 类型 必填 说明
upload_url string 是 上传的音乐文件 URL。可使用 POST /api/v1/files 返回的 url；该临时链接有效期为 1 小时。
title string 是 音乐曲目的标题
tags string 是 音乐风格和特征
negative_tags string 是 要排除的音乐风格
model string 是 模型版本：suno-v5、suno-v4.5-plus、suno-v4.5-all、suno-v4.5、suno-v4
callback_url string 否 接收完成通知的 URL
vocal_gender string 否 首选人声性别：male（男）或 female（女）。仅增加概率。
style_weight number 否 风格坚持权重（0-1）
weirdness_constraint number 否 创意约束（0-1）
audio_weight number 否 音频一致性权重（0-1）

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

成功回调示例：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] Relaxing piano melody flows",
      "model_name": "chirp-v4-5-plus",
      "title": "Relaxing Piano",
      "tags": ["Relaxing Piano", "Ambient", "Peaceful"],
      "duration": 182.32
    }
  ]
}

失败回调示例：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "generation_stage": "failed",
  "error": "Instrumental generation failed."
}

获取添加伴奏详情

查询添加伴奏状态：

curl "https://runapi.ai/api/v1/suno/add_instrumental/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/add_instrumental/TASK_ID')
request = Net::HTTP::Get.new(uri)

url = "https://runapi.ai/api/v1/suno/add_instrumental/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/add_instrumental/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询添加伴奏任务的状态和详情。

HTTP 请求

GET https://runapi.ai/api/v1/suno/add_instrumental/:id

URL 参数

参数 说明
id 提交请求时返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] Relaxing piano melody flows",
      "model_name": "chirp-v4-5-plus",
      "title": "Relaxing Piano",
      "tags": ["Relaxing Piano", "Ambient", "Peaceful"],
      "duration": 182.32
    }
  ]
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Instrumental generation failed."
}

人声和乐器分离

人声和乐器分离：

curl -X POST "https://runapi.ai/api/v1/suno/separate_audio_stems" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "audio_id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "type": "separate_vocal",
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  audio_id: "6949072e-5cdb-43a3-b093-56d16e582aeb",
  type: "separate_vocal",
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "audio_id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "type": "separate_vocal",
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  audio_id: "6949072e-5cdb-43a3-b093-56d16e582aeb",
  type: "separate_vocal",
  callback_url: "https://your-app.com/callbacks/suno"
})

将音乐分离为人声、伴奏和单独的乐器音轨。

HTTP 请求

POST https://runapi.ai/api/v1/suno/separate_audio_stems

请求体参数

参数 类型 必填 说明
task_id string 是 音乐生成任务的任务 ID
audio_id string 是 要分离的特定音轨 ID
type string 否 分离类型：separate_vocal（默认）或 split_stem。请查看 Suno 价格页面。
callback_url string 否 接收完成通知的 URL

分离类型： - separate_vocal：分离人声和伴奏（生成 2 个音轨） - split_stem：分离单独的乐器（生成 12+ 个音轨）

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

系统将在分离完成时向您的 callback_url 发送 POST 请求。

成功响应（separate_vocal）： - 包含 instrumental_url 和 vocal_url - 人声和伴奏音乐的清晰分离

成功响应（split_stem）： - 包含单独的乐器 URL - 包括 backing_vocals、bass、brass、drums、fx、guitar、keyboard、percussion、strings、synth、vocal、woodwinds

成功回调（separate_vocal）：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "separated_audios": {
    "instrumental_url": "https://file.runapi.ai/s/d92a****5528_Instrumental.mp3",
    "vocal_url": "https://file.runapi.ai/s/3d70****b172_Vocals.mp3"
  }
}

成功回调（split_stem）：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "separated_audios": {
    "backing_vocals_url": "https://file.runapi.ai/s/aadc****673d_Backing_Vocals.mp3",
    "bass_url": "https://file.runapi.ai/s/a3c2****26d33_Bass.mp3",
    "brass_url": "https://file.runapi.ai/s/334b****fdd44_Brass.mp3",
    "drums_url": "https://file.runapi.ai/s/ac75****78e44_Drums.mp3",
    "fx_url": "https://file.runapi.ai/s/a882****007d_FX.mp3",
    "guitar_url": "https://file.runapi.ai/s/064d****95b4_Guitar.mp3",
    "keyboard_url": "https://file.runapi.ai/s/adc9****d74e0_Keyboard.mp3",
    "piano_url": "https://file.runapi.ai/s/b1c2****3d4e_Piano.mp3",
    "percussion_url": "https://file.runapi.ai/s/0f70****618b7dc6_Percussion.mp3",
    "strings_url": "https://file.runapi.ai/s/4982****6b_Strings.mp3",
    "synth_url": "https://file.runapi.ai/s/56b2****8348_Synth.mp3",
    "vocal_url": "https://file.runapi.ai/s/0742****90ccb_Vocals.mp3",
    "woodwinds_url": "https://file.runapi.ai/s/d815****abb02_Woodwinds.mp3"
  }
}

失败回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Vocal separation failed."
}

获取人声分离详情

查询人声分离状态：

curl "https://runapi.ai/api/v1/suno/separate_audio_stems/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/separate_audio_stems/TASK_ID')
request = Net::HTTP::Get.new(uri)

url = "https://runapi.ai/api/v1/suno/separate_audio_stems/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/separate_audio_stems/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询人声分离任务的状态和详情。

HTTP 请求

GET https://runapi.ai/api/v1/suno/separate_audio_stems/:id

URL 参数

参数 说明
id 从人声移除端点返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

已完成（separate_vocal）：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "separated_audios": {
    "instrumental_url": "https://file.runapi.ai/s/d92a****5528_Instrumental.mp3",
    "vocal_url": "https://file.runapi.ai/s/3d70****b172_Vocals.mp3"
  }
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Vocal separation failed."
}

转换为 WAV 格式

转换为 WAV 格式：

curl -X POST "https://runapi.ai/api/v1/suno/convert_audio" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "audio_id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  audio_id: "6949072e-5cdb-43a3-b093-56d16e582aeb",
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "audio_id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  audio_id: "6949072e-5cdb-43a3-b093-56d16e582aeb",
  callback_url: "https://your-app.com/callbacks/suno"
})

将现有音乐曲目转换为高质量 WAV 格式。

HTTP 请求

POST https://runapi.ai/api/v1/suno/convert_audio

请求体参数

参数 类型 必填 说明
task_id string 是 音乐生成任务的任务 ID
audio_id string 是 要转换的音轨 ID
callback_url string 否 接收完成通知的 URL

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

成功回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "wav_url": "https://file.runapi.ai/s/04e6****e727.wav"
}

失败回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "WAV conversion failed."
}

获取 WAV 转换详情

查询 WAV 转换状态：

curl "https://runapi.ai/api/v1/suno/convert_audio/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/convert_audio/TASK_ID')
request = Net::HTTP::Get.new(uri)

url = "https://runapi.ai/api/v1/suno/convert_audio/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/convert_audio/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询 WAV 转换任务的状态和详情。

HTTP 请求

GET https://runapi.ai/api/v1/suno/convert_audio/:id

URL 参数

参数 说明
id 从 WAV 生成端点返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "wav_url": "https://file.runapi.ai/s/04e6****e727.wav"
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "WAV conversion failed."
}

从音频生成 MIDI

从音频生成 MIDI：

curl -X POST "https://runapi.ai/api/v1/suno/generate_midi" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  callback_url: "https://your-app.com/callbacks/suno"
})

将分离的音轨转换为 MIDI 格式，提供详细的音符信息。需要提供先前 split_stem 人声分离任务的任务 ID。

HTTP 请求

POST https://runapi.ai/api/v1/suno/generate_midi

请求体参数

参数 类型 必填 说明
task_id string 是 已完成的音轨分离任务的任务 ID
callback_url string 否 接收完成通知的 URL

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

成功响应： - 包含 instruments 数组和检测到的乐器 - 每个乐器包含音符序列数据 - 音符包括音高（MIDI 0-127）、开始/结束时间、力度

成功回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "instruments": [
    {
      "name": "Drums",
      "notes": [
        {
          "pitch": 73,
          "start_time": 0.036458333333333336,
          "end_time": 0.18229166666666666,
          "velocity": 1
        }
      ]
    },
    {
      "name": "Electric Bass (finger)",
      "notes": [
        {
          "pitch": 44,
          "start_time": 7.6875,
          "end_time": 7.911458333333333,
          "velocity": 1
        }
      ]
    }
  ]
}

失败回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "MIDI generation failed."
}

获取 MIDI 详情

查询 MIDI 状态：

curl "https://runapi.ai/api/v1/suno/generate_midi/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/generate_midi/TASK_ID')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

url = "https://runapi.ai/api/v1/suno/generate_midi/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/generate_midi/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询 MIDI 生成任务的状态和详情。

HTTP 请求

GET https://runapi.ai/api/v1/suno/generate_midi/:id

URL 参数

参数 说明
id 从 MIDI 生成端点返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing",
  "instruments": []
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "instruments": [
    {
      "name": "Drums",
      "notes": [
        {
          "pitch": 73,
          "start_time": 0.036458333333333336,
          "end_time": 0.18229166666666666,
          "velocity": 1
        }
      ]
    }
  ]
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "MIDI generation failed.",
  "instruments": []
}

生成音乐封面

生成音乐封面：

curl -X POST "https://runapi.ai/api/v1/suno/generate_artwork" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  callback_url: "https://your-app.com/callbacks/suno"
})

为生成的音乐创建个性化封面图片。

HTTP 请求

POST https://runapi.ai/api/v1/suno/generate_artwork

请求体参数

参数 类型 必填 说明
task_id string 是 从音乐生成端点返回的原始音乐任务 ID
callback_url string 否 接收完成通知的 URL

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

成功响应： - 包含 covers 数组和生成的封面图片 - 通常生成 2 个不同风格的封面图片 - 封面 URL 是临时链接，有效期为 7 天；请下载并保存到你自己的持久化存储以供长期使用

成功回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "covers": [
    {
      "url": "https://tempfile.runapi.ai/s/1753958521_6c1b3015141849d1a9bf17b738ce9347.png"
    },
    {
      "url": "https://tempfile.runapi.ai/s/1753958524_c153143acc6340908431cf0e90cbce9e.png"
    }
  ]
}

失败回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Cover generation failed.",
  "covers": []
}

获取音乐封面

查询音乐封面状态：

curl "https://runapi.ai/api/v1/suno/generate_artwork/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/generate_artwork/TASK_ID')
request = Net::HTTP::Get.new(uri)

url = "https://runapi.ai/api/v1/suno/generate_artwork/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/generate_artwork/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询音乐封面生成任务的状态和结果。

HTTP 请求

GET https://runapi.ai/api/v1/suno/generate_artwork/:id

URL 参数

参数 说明
id 从生成音乐封面端点返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing",
  "covers": []
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "covers": [
    {
      "url": "https://tempfile.runapi.ai/s/1753958521_6c1b3015141849d1a9bf17b738ce9347.png"
    },
    {
      "url": "https://tempfile.runapi.ai/s/1753958524_c153143acc6340908431cf0e90cbce9e.png"
    }
  ]
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Cover generation failed.",
  "covers": []
}

创建音乐视频

创建音乐视频：

curl -X POST "https://runapi.ai/api/v1/suno/visualize_music" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "audio_id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "callback_url": "https://your-app.com/callbacks/suno",
    "author": "Suno Artist",
    "domain_name": "music.example.com"
  }'

request.body = {
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  audio_id: "6949072e-5cdb-43a3-b093-56d16e582aeb",
  callback_url: "https://your-app.com/callbacks/suno",
  author: "Suno Artist",
  domain_name: "music.example.com"
}.to_json

data = {
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "audio_id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "callback_url": "https://your-app.com/callbacks/suno",
    "author": "Suno Artist",
    "domain_name": "music.example.com"
}

body: JSON.stringify({
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  audio_id: "6949072e-5cdb-43a3-b093-56d16e582aeb",
  callback_url: "https://your-app.com/callbacks/suno",
  author: "Suno Artist",
  domain_name: "music.example.com"
})

为音乐曲目生成带可视化效果的 MP4 视频。

HTTP 请求

POST https://runapi.ai/api/v1/suno/visualize_music

请求体参数

参数 类型 必填 说明
task_id string 是 音乐生成任务的任务 ID
audio_id string 是 要转换为视频的特定音轨 ID
callback_url string 否 接收完成通知的 URL
author string 否 视频上显示的艺术家/创作者名称（最多 50 字符）
domain_name string 否 作为水印显示的网站/品牌（最多 50 字符）

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

成功回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "video_url": "https://file.runapi.ai/videos/video_847715e66259.mp4"
}

失败回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Video generation failed."
}

获取音乐视频详情

查询音乐视频状态：

curl "https://runapi.ai/api/v1/suno/visualize_music/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/visualize_music/TASK_ID')
request = Net::HTTP::Get.new(uri)

url = "https://runapi.ai/api/v1/suno/visualize_music/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/visualize_music/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询音乐视频生成任务的状态和详情。

HTTP 请求

GET https://runapi.ai/api/v1/suno/visualize_music/:id

URL 参数

参数 说明
id 从音乐视频生成端点返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "video_url": "https://file.runapi.ai/videos/video_847715e66259.mp4"
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Video generation failed."
}

增强音乐风格

增强音乐风格：

curl -X POST "https://runapi.ai/api/v1/suno/boost_style" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Pop, Mysterious"
  }'

request.body = {
  description: "Pop, Mysterious"
}.to_json

data = {"description": "Pop, Mysterious"}

body: JSON.stringify({description: "Pop, Mysterious"})

生成增强的音乐风格描述，以获得更详细的提示。

HTTP 请求

POST https://runapi.ai/api/v1/suno/boost_style

请求体参数

参数 类型 必填 说明
description string 是 简洁的风格关键词或简要描述

响应

立即返回增强的风格描述（同步响应）。

{
  "style": "Pop, Mysterious, Upbeat, Electronic, Synth-driven, Catchy hooks"
}

获取时间戳歌词

获取时间戳歌词：

curl -X POST "https://runapi.ai/api/v1/suno/get_timestamped_lyrics" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "b7e7c624-c244-4ba7-a9f7-7d85da73cf03",
    "audio_id": "0aac6db8-cbe9-4af2-aea6-d7aa7d3a2355"
  }'

request.body = {
  task_id: "b7e7c624-c244-4ba7-a9f7-7d85da73cf03",
  audio_id: "0aac6db8-cbe9-4af2-aea6-d7aa7d3a2355"
}.to_json

data = {
    "task_id": "b7e7c624-c244-4ba7-a9f7-7d85da73cf03",
    "audio_id": "0aac6db8-cbe9-4af2-aea6-d7aa7d3a2355"
}

body: JSON.stringify({
  task_id: "b7e7c624-c244-4ba7-a9f7-7d85da73cf03",
  audio_id: "0aac6db8-cbe9-4af2-aea6-d7aa7d3a2355"
})

检索用于音频播放期间同步显示的时间戳歌词。

HTTP 请求

POST https://runapi.ai/api/v1/suno/get_timestamped_lyrics

请求体参数

参数 类型 必填 说明
task_id string 是 音乐生成任务的任务 ID
audio_id string 是 要检索歌词的特定音频 ID

响应

立即返回时间戳歌词数据（同步响应）。该接口不返回 processing 状态。

{
  "aligned_words": [
    {
      "word": "[Verse]\nWaggin'",
      "success": true,
      "start_time": 1.36,
      "end_time": 1.79,
      "palign": 0
    },
    {
      "word": "my",
      "success": true,
      "start_time": 1.79,
      "end_time": 1.95,
      "palign": 0
    }
  ],
  "waveform_data": [0, 1, 0.5, 0.75],
  "hoot_cer": 0.3803191489361702,
  "is_streamed": false
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Timestamped lyrics generation failed."
}

生成角色

生成角色：

curl -X POST "https://runapi.ai/api/v1/suno/generate_persona" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "audio_id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "name": "Electronic Pop Singer",
    "description": "A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones"
  }'

request.body = {
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  audio_id: "6949072e-5cdb-43a3-b093-56d16e582aeb",
  name: "Electronic Pop Singer",
  description: "A modern electronic music style pop singer"
}.to_json

data = {
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "audio_id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "name": "Electronic Pop Singer",
    "description": "A modern electronic music style pop singer"
}

body: JSON.stringify({
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  audio_id: "6949072e-5cdb-43a3-b093-56d16e582aeb",
  name: "Electronic Pop Singer",
  description: "A modern electronic music style pop singer"
})

基于生成的音乐创建个性化音乐角色。

HTTP 请求

POST https://runapi.ai/api/v1/suno/generate_persona

请求体参数

参数 类型 必填 说明
task_id string 是 来自音乐生成端点的任务 ID
audio_id string 是 要为其创建角色的特定音频 ID
name string 是 角色的易于识别的名称
description string 是 角色的音乐特征和风格

响应

立即返回生成的角色（同步响应）。

{
  "persona": {
    "id": "abc123def456",
    "name": "Electronic Pop Singer",
    "description": "A modern electronic music style pop singer, skilled in dynamic rhythms and synthesizer tones"
  }
}

替换音乐片段

替换音乐片段：

curl -X POST "https://runapi.ai/api/v1/suno/replace_section" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "audio_id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "lyrics": "[Verse]\nA calm and relaxing piano track.",
    "tags": "Jazz",
    "title": "Relaxing Piano",
    "infill_start_time": 10.5,
    "infill_end_time": 20.75,
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  audio_id: "6949072e-5cdb-43a3-b093-56d16e582aeb",
  lyrics: "[Verse]\nA calm and relaxing piano track.",
  tags: "Jazz",
  title: "Relaxing Piano",
  infill_start_time: 10.5,
  infill_end_time: 20.75,
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "audio_id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "lyrics": "[Verse]\nA calm and relaxing piano track.",
    "tags": "Jazz",
    "title": "Relaxing Piano",
    "infill_start_time": 10.5,
    "infill_end_time": 20.75,
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  task_id: "03fe3e68-2dec-487c-a810-885667aed19c",
  audio_id: "6949072e-5cdb-43a3-b093-56d16e582aeb",
  lyrics: "[Verse]\nA calm and relaxing piano track.",
  tags: "Jazz",
  title: "Relaxing Piano",
  infill_start_time: 10.5,
  infill_end_time: 20.75,
  callback_url: "https://your-app.com/callbacks/suno"
})

替换现有音乐中的特定时间段。

HTTP 请求

POST https://runapi.ai/api/v1/suno/replace_section

请求体参数

参数 类型 必填 说明
task_id string 是 标识源音乐的原始任务 ID
audio_id string 是 要替换的音轨的唯一标识符
lyrics string 是 替换片段的精确歌词
tags string 是 音乐风格标签
title string 是 音乐标题
infill_start_time number 是 开始时间（秒，2 位小数）
infill_end_time number 是 结束时间（秒，2 位小数）
callback_url string 否 接收完成通知的 URL
negative_tags string 否 排除的音乐风格
full_lyrics string 否 修改后的完整歌词

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

成功回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "track": {
    "id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "audio_url": "https://file.runapi.ai/****.mp3",
    "stream_audio_url": "https://file.runapi.ai/****",
    "image_url": "https://file.runapi.ai/****.jpeg",
    "lyrics": "[Verse]\nA calm and relaxing piano track.",
    "model_name": "chirp-v3-5",
    "title": "Relaxing Piano",
    "tags": ["Jazz"],
    "duration": 198.44
  }
}

失败回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Audio generation failed."
}

获取替换片段详情

查询替换片段状态：

curl "https://runapi.ai/api/v1/suno/replace_section/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/replace_section/TASK_ID')
request = Net::HTTP::Get.new(uri)

url = "https://runapi.ai/api/v1/suno/replace_section/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/replace_section/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询替换片段任务的状态和结果。

HTTP 请求

GET https://runapi.ai/api/v1/suno/replace_section/:id

URL 参数

参数 说明
id 从替换音乐片段端点返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "track": {
    "id": "6949072e-5cdb-43a3-b093-56d16e582aeb",
    "audio_url": "https://file.runapi.ai/****.mp3",
    "stream_audio_url": "https://file.runapi.ai/****",
    "image_url": "https://file.runapi.ai/****.jpeg",
    "lyrics": "[Verse]\nA calm and relaxing piano track.",
    "model_name": "chirp-v3-5",
    "title": "Relaxing Piano",
    "tags": ["Jazz"],
    "duration": 198.44
  }
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Audio generation failed."
}

上传并翻唱

Upload and cover 音频：

curl -X POST "https://runapi.ai/api/v1/suno/cover_audio" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_url": "https://cdn.runapi.ai/public/samples/music.mp3",
    "vocal_mode": "instrumental",
    "style": "Classical",
    "title": "Peaceful Piano Meditation",
    "model": "suno-v5",
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  upload_url: "https://cdn.runapi.ai/public/samples/music.mp3",
  vocal_mode: "instrumental",
  style: "Classical",
  title: "Peaceful Piano Meditation",
  model: "suno-v5",
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "upload_url": "https://cdn.runapi.ai/public/samples/music.mp3",
    "vocal_mode": "instrumental",
    "style": "Classical",
    "title": "Peaceful Piano Meditation",
    "model": "suno-v5",
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  upload_url: "https://cdn.runapi.ai/public/samples/music.mp3",
  vocal_mode: "instrumental",
  style: "Classical",
  title: "Peaceful Piano Meditation",
  model: "suno-v5",
  callback_url: "https://your-app.com/callbacks/suno"
})

将上传的音频转换为新风格，同时保留其核心旋律。

HTTP 请求

POST https://runapi.ai/api/v1/suno/cover_audio

请求体参数

请求形态

选择 vocal_mode。每个请求都需要 upload_url 和 model，也可以提供 callback_url。

参数 类型 必填 说明
upload_url string 是 待处理音频文件的 URL（最长 8 分钟）。可使用 POST /api/v1/files 返回的 url；该临时链接有效期为 1 小时。
model string 是 模型版本：suno-v5、suno-v4.5-plus、suno-v4.5-all、suno-v4.5、suno-v4
callback_url string 否 接收完成通知的 URL
vocal_mode string 是 auto_lyrics、exact_lyrics 或 instrumental。
prompt string 否 翻唱 brief，用于自动生成歌词。
lyrics string 否 翻唱的精确歌词。
style string 否 音乐风格。
title string 否 音乐标题。
persona_id string 否 要应用的角色 ID。通过生成角色创建。
persona_type string 否 角色类型，配合 persona_id 使用。可选值：style 应用风格特征，voice 应用声音特征（仅 suno-v5）。无 persona_id 时忽略。
negative_tags string 否 要排除的风格
vocal_gender string 否 人声偏好：male（男）或 female（女）。仅增加概率。
style_weight number 否 风格坚持权重（0-1）
weirdness_constraint number 否 创意约束（0-1）
audio_weight number 否 音频一致性权重（0-1）

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

成功回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] Calm piano melodies flow gently",
      "model_name": "chirp-v3-5",
      "title": "Peaceful Piano Meditation (Cover)",
      "tags": ["classical", "relaxing"],
      "duration": 198.44
    }
  ]
}

失败回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "generation_stage": "failed",
  "error": "Cover generation failed."
}

获取上传翻唱详情

查询 Upload and Covers 状态：

curl "https://runapi.ai/api/v1/suno/cover_audio/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/cover_audio/TASK_ID')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

url = "https://runapi.ai/api/v1/suno/cover_audio/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/cover_audio/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询 Upload and Covers 任务的状态和详情。

HTTP 请求

GET https://runapi.ai/api/v1/suno/cover_audio/:id

URL 参数

参数 说明
id 提交 Upload and Covers 请求时返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] Calm piano melodies flow gently",
      "model_name": "chirp-v3-5",
      "title": "Peaceful Piano Meditation (Cover)",
      "tags": ["classical", "relaxing"],
      "duration": 198.44
    }
  ]
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Cover generation failed."
}

上传并续写

扩展音频文件：

curl -X POST "https://runapi.ai/api/v1/suno/extend_music" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_url": "https://cdn.runapi.ai/public/samples/music.mp3",
    "parameter_mode": "custom",
    "prompt": "Extend the music with more relaxing piano notes",
    "style": "Classical",
    "title": "Peaceful Piano Extended",
    "continue_at": 60,
    "model": "suno-v5",
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  upload_url: "https://cdn.runapi.ai/public/samples/music.mp3",
  parameter_mode: "custom",
  prompt: "Extend the music with more relaxing piano notes",
  style: "Classical",
  title: "Peaceful Piano Extended",
  continue_at: 60,
  model: "suno-v5",
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "upload_url": "https://cdn.runapi.ai/public/samples/music.mp3",
    "parameter_mode": "custom",
    "prompt": "Extend the music with more relaxing piano notes",
    "style": "Classical",
    "title": "Peaceful Piano Extended",
    "continue_at": 60,
    "model": "suno-v5",
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  upload_url: "https://cdn.runapi.ai/public/samples/music.mp3",
  parameter_mode: "custom",
  prompt: "Extend the music with more relaxing piano notes",
  style: "Classical",
  title: "Peaceful Piano Extended",
  continue_at: 60,
  model: "suno-v5",
  callback_url: "https://your-app.com/callbacks/suno"
})

扩展上传的音频曲目，同时保留原始风格。

HTTP 请求

POST https://runapi.ai/api/v1/suno/extend_music

请求体参数

参数 类型 必填 说明
upload_url string 是 待处理音频文件的 URL（最长 8 分钟）。可使用 POST /api/v1/files 返回的 url；该临时链接有效期为 1 小时。
parameter_mode string 是 source 继承源音频参数，或 custom 使用本次请求参数
model string 是 模型版本：suno-v5、suno-v4.5-plus、suno-v4.5-all、suno-v4.5、suno-v4
callback_url string 否 接收完成通知的 URL
continue_at number 条件 开始时间（秒）（当 parameter_mode 为 custom 时必填）
prompt string 条件 扩展描述（当 parameter_mode 为 source 或 instrumental 为 false 时必填）
style string 条件 音乐风格（当 parameter_mode 为 custom 时必填）
title string 条件 音乐标题（当 parameter_mode 为 custom 时必填）
instrumental boolean 条件 音频是否为纯音乐（当 parameter_mode 为 custom 时必填）
persona_id string 否 当 parameter_mode 为 custom 时要应用的角色 ID。通过生成角色创建。
persona_type string 否 角色类型，配合 persona_id 使用。可选值：style 应用风格特征，voice 应用声音特征（仅 suno-v5）。无 persona_id 时忽略。
negative_tags string 否 要排除的风格
vocal_gender string 否 首选人声性别：male（男）或 female（女）。仅在 parameter_mode: "custom" 时生效。仅增加概率。
style_weight number 否 风格坚持权重（0-1）
weirdness_constraint number 否 创意约束（0-1）
audio_weight number 否 音频一致性权重（0-1）

响应

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

Callback 格式

成功回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] Continue the beautiful melody",
      "model_name": "chirp-v3-5",
      "title": "Peaceful Piano Extended",
      "tags": ["classical", "relaxing"],
      "duration": 298.44
    }
  ]
}

失败回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "generation_stage": "failed",
  "error": "Extension generation failed."
}

获取上传续写详情

查询 Upload and Extensions 状态：

curl "https://runapi.ai/api/v1/suno/extend_music/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/extend_music/TASK_ID')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

url = "https://runapi.ai/api/v1/suno/extend_music/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/extend_music/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询 Upload and Extensions 任务的状态和详情。

HTTP 请求

GET https://runapi.ai/api/v1/suno/extend_music/:id

URL 参数

参数 说明
id 提交 Upload and Extensions 请求时返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] Continue the beautiful melody",
      "model_name": "chirp-v3-5",
      "title": "Peaceful Piano Extended",
      "tags": ["classical", "relaxing"],
      "duration": 298.44
    }
  ]
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "error": "Extension generation failed."
}

Mashup

使用两个音频文件创建混音：

curl -X POST "https://runapi.ai/api/v1/suno/create_mashup" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_url_list": ["https://cdn.runapi.ai/public/samples/music.mp3", "https://cdn.runapi.ai/public/samples/music.mp3"],
    "vocal_mode": "exact_lyrics",
    "lyrics": "[Verse]\nA calm and relaxing piano track with soft melodies",
    "style": "Jazz",
    "title": "Relaxing Piano",
    "model": "suno-v4",
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  upload_url_list: ["https://cdn.runapi.ai/public/samples/music.mp3", "https://cdn.runapi.ai/public/samples/music.mp3"],
  vocal_mode: "exact_lyrics",
  lyrics: "[Verse]\nA calm and relaxing piano track with soft melodies",
  style: "Jazz",
  title: "Relaxing Piano",
  model: "suno-v4",
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "upload_url_list": ["https://cdn.runapi.ai/public/samples/music.mp3", "https://cdn.runapi.ai/public/samples/music.mp3"],
    "vocal_mode": "exact_lyrics",
    "lyrics": "[Verse]\nA calm and relaxing piano track with soft melodies",
    "style": "Jazz",
    "title": "Relaxing Piano",
    "model": "suno-v4",
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  upload_url_list: ["https://cdn.runapi.ai/public/samples/music.mp3", "https://cdn.runapi.ai/public/samples/music.mp3"],
  vocal_mode: "exact_lyrics",
  lyrics: "[Verse]\nA calm and relaxing piano track with soft melodies",
  style: "Jazz",
  title: "Relaxing Piano",
  model: "suno-v4",
  callback_url: "https://your-app.com/callbacks/suno"
})

将两个上传的音频文件通过 AI 混音生成技术组合成一首全新的作品。

HTTP 请求

POST https://runapi.ai/api/v1/suno/create_mashup

请求体参数

请求形态

选择 vocal_mode。每个请求都需要 upload_url_list 和 model，也可以提供 callback_url。

参数 类型 必填 描述
upload_url_list array 是 两个可公开访问的音频文件 URL（必须恰好 2 个）
model string 是 模型版本：suno-v5、suno-v4.5-plus、suno-v4.5-all、suno-v4.5、suno-v4
callback_url string 否 接收完成通知的 URL
vocal_mode string 是 auto_lyrics、exact_lyrics 或 instrumental。
prompt string 否 Mashup brief，用于自动生成歌词。
lyrics string 否 Mashup 的精确歌词。
style string 否 音乐风格。
title string 否 音乐标题。
persona_id string 否 要应用的角色 ID。通过生成角色创建。
persona_type string 否 角色类型，配合 persona_id 使用。可选值：style 应用风格特征，voice 应用声音特征（仅 suno-v5）。无 persona_id 时忽略。
vocal_gender string 否 人声偏好：male（男）或 female（女）。仅提高概率。
style_weight number 否 风格贴合度权重（0-1）
weirdness_constraint number 否 创意约束（0-1）
audio_weight number 否 音频一致性权重（0-1）

响应

返回用于跟踪生成状态的任务 ID。

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

回调格式

成功回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] Night city lights shining bright",
      "model_name": "chirp-v4",
      "title": "Relaxing Piano",
      "tags": ["jazz", "piano"],
      "duration": 198.44
    }
  ]
}

失败回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "generation_stage": "failed",
  "error": "Mashup generation failed."
}

获取 Mashup 详情

查询混音状态：

curl "https://runapi.ai/api/v1/suno/create_mashup/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/create_mashup/TASK_ID')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

url = "https://runapi.ai/api/v1/suno/create_mashup/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/create_mashup/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询混音任务的状态和详情。

HTTP 请求

GET https://runapi.ai/api/v1/suno/create_mashup/:id

URL 参数

参数 描述
id 提交混音请求时返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "lyrics": "[Verse] Night city lights shining bright",
      "model_name": "chirp-v4",
      "title": "Relaxing Piano",
      "tags": ["jazz", "piano"],
      "duration": 198.44
    }
  ]
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "generation_stage": "failed",
  "error": "Mashup generation failed."
}

生成音效

通过提示词创建环境音或可循环的音效：

curl -X POST "https://runapi.ai/api/v1/suno/text_to_sound" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Rain on a tin roof, distant thunder, cozy atmosphere",
    "model": "suno-v5",
    "sound_loop": true,
    "sound_tempo": 90,
    "sound_key": "Cm",
    "grab_lyrics": false,
    "callback_url": "https://your-app.com/callbacks/suno"
  }'

request.body = {
  prompt: "Rain on a tin roof, distant thunder, cozy atmosphere",
  model: "suno-v5",
  sound_loop: true,
  sound_tempo: 90,
  sound_key: "Cm",
  grab_lyrics: false,
  callback_url: "https://your-app.com/callbacks/suno"
}.to_json

data = {
    "prompt": "Rain on a tin roof, distant thunder, cozy atmosphere",
    "model": "suno-v5",
    "sound_loop": True,
    "sound_tempo": 90,
    "sound_key": "Cm",
    "grab_lyrics": False,
    "callback_url": "https://your-app.com/callbacks/suno"
}

body: JSON.stringify({
  prompt: "Rain on a tin roof, distant thunder, cozy atmosphere",
  model: "suno-v5",
  sound_loop: true,
  sound_tempo: 90,
  sound_key: "Cm",
  grab_lyrics: false,
  callback_url: "https://your-app.com/callbacks/suno"
})

通过文本提示词生成环境音、音效或可循环音轨，并支持 BPM 与调式控制。

HTTP 请求

POST https://runapi.ai/api/v1/suno/text_to_sound

请求体参数

参数 类型 必填 描述
prompt string 是 音效描述，最多 500 个字符
model string 是 模型版本：suno-v5、suno-v5.5
sound_loop boolean 否 是否生成可循环音频。默认 false
sound_tempo integer 否 每分钟节拍数，范围 1–300
sound_key string 否 调式：Cm、C#m、Dm、D#m、Em、Fm、F#m、Gm、G#m、Am、A#m、Bm、C、C#、D、D#、E、F、F#、G、G#、A、A#、B。默认 Any
grab_lyrics boolean 否 是否抓取歌词字幕供后续读取。默认 false
callback_url string 否 接收完成通知的 URL

响应

返回用于跟踪生成状态的任务 ID。

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

回调格式

成功回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "prompt": "Rain on a tin roof, distant thunder",
      "model_name": "chirp-v5",
      "title": "Rainy Night",
      "tags": ["ambient", "rain", "loopable"],
      "duration": 32.5
    }
  ]
}

失败回调：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "generation_stage": "failed",
  "error": "Generation failed, please retry."
}

获取音效详情

查询音效任务状态：

curl "https://runapi.ai/api/v1/suno/text_to_sound/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

uri = URI('https://runapi.ai/api/v1/suno/text_to_sound/TASK_ID')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

url = "https://runapi.ai/api/v1/suno/text_to_sound/TASK_ID"
response = requests.get(url, headers=headers)

fetch('https://runapi.ai/api/v1/suno/text_to_sound/TASK_ID', {
  method: 'GET',
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

查询音效生成任务的状态和详情。

HTTP 请求

GET https://runapi.ai/api/v1/suno/text_to_sound/:id

URL 参数

参数 描述
id 提交音效生成请求时返回的任务 ID

响应

处理中：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "generation_stage": "all_audios_ready",
  "audios": [
    {
      "id": "8551****662c",
      "audio_url": "https://file.runapi.ai/****.mp3",
      "stream_audio_url": "https://file.runapi.ai/****",
      "image_url": "https://file.runapi.ai/****.jpeg",
      "prompt": "Rain on a tin roof, distant thunder",
      "model_name": "chirp-v5",
      "title": "Rainy Night",
      "tags": ["ambient", "rain", "loopable"],
      "duration": 32.5
    }
  ]
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "generation_stage": "failed",
  "error": "Generation failed, please retry."
}

生成验证短语

从源人声片段生成验证短语：

curl -X POST "https://runapi.ai/api/v1/suno/voice_to_validation_phrase" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://file.runapi.ai/source-vocal.mp3",
    "vocal_start_seconds": 2,
    "vocal_end_seconds": 12,
    "language": "zh",
    "callback_url": "https://your-app.com/callbacks/suno-voice"
  }'

创建一段用户后续可朗读的验证短语。人声窗口必须使用整数秒，并且 vocal_end_seconds 必须大于 vocal_start_seconds。

HTTP 请求

POST https://runapi.ai/api/v1/suno/voice_to_validation_phrase

请求体参数

参数 类型 必填 说明
voice_url string 是 源人声录音的公开 URL
vocal_start_seconds integer 是 人声片段开始时间，单位秒
vocal_end_seconds integer 是 人声片段结束时间，单位秒；必须大于 vocal_start_seconds
language string 否 短语语言：en、zh、es、fr、pt、de、ja、ko、hi、ru
callback_url string 否 HTTPS 回调地址

响应

HTTP 202 - 任务已接受：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "processing"
}

Callback 格式

短语已就绪：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "provider_status": "wait_validating",
  "validation_phrase": "Harmonies fill the air with joyful melodies tonight"
}

失败：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "failed",
  "provider_status": "processing_validate_fail",
  "error": "Validation phrase generation failed."
}

查询验证短语详情

查询验证短语任务状态：

curl "https://runapi.ai/api/v1/suno/voice_to_validation_phrase/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

查询验证短语任务状态和短语内容。

HTTP 请求

GET https://runapi.ai/api/v1/suno/voice_to_validation_phrase/:id

URL 参数

参数 描述
id 生成验证短语端点返回的任务 ID

响应

已完成：

{
  "id": "03fe3e68-2dec-487c-a810-885667aed19c",
  "status": "completed",
  "provider_status": "wait_validating",
  "validation_phrase": "Harmonies fill the air with joyful melodies tonight"
}

重新生成验证短语

为之前的验证短语任务生成新短语：

curl -X POST "https://runapi.ai/api/v1/suno/regenerate_validation_phrase" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "callback_url": "https://your-app.com/callbacks/suno-voice"
  }'

当上一条短语过期、难以朗读或需要在录制验证音频前替换时使用。task_id 必须引用同一账户下已有的 Suno 验证短语任务。

HTTP 请求

POST https://runapi.ai/api/v1/suno/regenerate_validation_phrase

请求体参数

参数 类型 必填 说明
task_id string 是 来自生成验证短语或之前重新生成任务的任务 ID
callback_url string 否 HTTPS 回调地址

响应

HTTP 202 - 任务已接受：

{
  "id": "04ab2c8d-15b4-4b77-833f-9a462ce02ef6",
  "status": "processing"
}

Callback 格式

短语已就绪：

{
  "id": "04ab2c8d-15b4-4b77-833f-9a462ce02ef6",
  "status": "completed",
  "provider_status": "wait_validating",
  "validation_phrase": "Silver echoes drift across the midnight ocean"
}

查询重新生成验证短语详情

查询重新生成验证短语任务状态：

curl "https://runapi.ai/api/v1/suno/regenerate_validation_phrase/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

HTTP 请求

GET https://runapi.ai/api/v1/suno/regenerate_validation_phrase/:id

URL 参数

参数 描述
id 重新生成验证短语端点返回的任务 ID

响应

已完成：

{
  "id": "04ab2c8d-15b4-4b77-833f-9a462ce02ef6",
  "status": "completed",
  "provider_status": "wait_validating",
  "validation_phrase": "Silver echoes drift across the midnight ocean"
}

生成自定义声音

从验证短语任务创建可复用的自定义声音：

curl -X POST "https://runapi.ai/api/v1/suno/generate_voice" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "03fe3e68-2dec-487c-a810-885667aed19c",
    "verify_url": "https://file.runapi.ai/verify-read.mp3",
    "voice_name": "Warm Test Voice",
    "description": "Warm vocal identity",
    "style": "Pop, Female Vocal",
    "singer_skill_level": "advanced",
    "callback_url": "https://your-app.com/callbacks/suno-voice"
  }'

基于已有验证短语任务和用户朗读该短语的录音创建自定义声音。完成响应包含 voice_id；在支持的 Suno v5 音乐生成端点中，可将该值作为 persona_id，并把 persona_type 设置为 "voice"。

HTTP 请求

POST https://runapi.ai/api/v1/suno/generate_voice

请求体参数

参数 类型 必填 说明
task_id string 是 来自生成验证短语或重新生成验证短语的任务 ID
verify_url string 是 用户朗读验证短语录音的公开 URL
voice_name string 否 自定义声音显示名称
description string 否 自定义声音描述
style string 否 声音风格标签
singer_skill_level string 否 演唱技能级别：beginner、intermediate、advanced、professional
callback_url string 否 HTTPS 回调地址

响应

HTTP 202 - 任务已接受：

{
  "id": "05bd3d12-92e6-4e8d-98f4-90ae86dfe6f1",
  "status": "processing"
}

Callback 格式

声音已就绪：

{
  "id": "05bd3d12-92e6-4e8d-98f4-90ae86dfe6f1",
  "status": "completed",
  "provider_status": "success",
  "voice_id": "voice_custom_123"
}

失败：

{
  "id": "05bd3d12-92e6-4e8d-98f4-90ae86dfe6f1",
  "status": "failed",
  "provider_status": "fail",
  "error": "Custom voice generation failed."
}

查询自定义声音详情

查询自定义声音生成状态：

curl "https://runapi.ai/api/v1/suno/generate_voice/:id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

查询自定义声音任务状态和完成后的 voice_id。

HTTP 请求

GET https://runapi.ai/api/v1/suno/generate_voice/:id

URL 参数

参数 描述
id 生成自定义声音端点返回的任务 ID

响应

已完成：

{
  "id": "05bd3d12-92e6-4e8d-98f4-90ae86dfe6f1",
  "status": "completed",
  "provider_status": "success",
  "voice_id": "voice_custom_123"
}

检查自定义声音

确认生成的自定义声音是否可用：

curl -X POST "https://runapi.ai/api/v1/suno/check_voice" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "05bd3d12-92e6-4e8d-98f4-90ae86dfe6f1"
  }'

在把 voice_id 作为 persona_id 并配合 persona_type: "voice" 使用前，可先检查对应的生成自定义声音任务是否可用。

HTTP 请求

POST https://runapi.ai/api/v1/suno/check_voice

请求体参数

参数 类型 必填 说明
task_id string 是 来自生成自定义声音的任务 ID

响应

可用：

{
  "is_available": true
}

Nano Banana

Nano Banana 在 RunAPI 上可以根据文本提示创建高质量图像。

版本对比

功能 基础版 (nano-banana) 专业版 (nano-banana-pro) V2 (nano-banana-2)
最大分辨率 1024px 4K 4K
尺寸控制 aspect_ratio (11 种预设) aspect_ratio + output_resolution aspect_ratio (15 种预设) + output_resolution
最大提示词 5,000 字符 5,000 字符 20,000 字符
最大图片数 每次请求 8 张 每次请求 8 张 每次请求 14 张
最适合 快速原型 生产质量 复杂多面板提示

Nano Banana 端点概览

任务 端点 模型
生成图像（标准） 生成图像 (基础版) nano-banana
生成图像（高质量） 生成图像 (专业版) nano-banana-pro
生成图像（V2） 生成图像 (V2) nano-banana-2
编辑/修改现有图像 编辑图像 nano-banana-edit
检查生成状态 获取生成状态 -
检查编辑状态 获取编辑状态 -

生成图像 (基础版)

使用基础版模型创建图像生成任务：

curl -X POST "https://runapi.ai/api/v1/nano_banana/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "callback_url": "https://your-domain.com/api/callback",
    "prompt": "一幅超现实主义的画作，巨大的香蕉漂浮在太空中，背景是星星和星系，色彩鲜艳，数字艺术",
    "output_format": "png",
    "aspect_ratio": "1:1",
    "reference_image_urls": []
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/nano_banana/text_to_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'nano-banana',
  callback_url: 'https://your-domain.com/api/callback',
  prompt: '一幅超现实主义的画作，巨大的香蕉漂浮在太空中，背景是星星和星系，色彩鲜艳，数字艺术',
  output_format: 'png',
  aspect_ratio: '1:1',
  reference_image_urls: []
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/nano_banana/text_to_image'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'nano-banana',
    'callback_url': 'https://your-domain.com/api/callback',
    'prompt': '一幅超现实主义的画作，巨大的香蕉漂浮在太空中，背景是星星和星系，色彩鲜艳，数字艺术',
    'output_format': 'png',
    'aspect_ratio': '1:1',
    'reference_image_urls': []
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'nano-banana',
  callback_url: 'https://your-domain.com/api/callback',
  prompt: '一幅超现实主义的画作，巨大的香蕉漂浮在太空中，背景是星星和星系，色彩鲜艳，数字艺术',
  output_format: 'png',
  aspect_ratio: '1:1',
  reference_image_urls: []
};

fetch('https://runapi.ai/api/v1/nano_banana/text_to_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

使用基础版 Nano Banana 模型创建新的图像生成任务。请求是异步处理的。

HTTP 请求

POST https://runapi.ai/api/v1/nano_banana/text_to_image

请求参数

参数 类型 必需 说明
model string 是 使用的模型：nano-banana 表示基础版
prompt string 是 期望图像的文本描述 (最多 5000 字符)
callback_url string 否 完成回调的 URL
output_format string 否 输出格式: png, jpg (默认: png)
aspect_ratio string 否 输出宽高比: 1:1, 9:16, 16:9, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9, auto (默认: 1:1)
reference_image_urls array 否 参考图像 URL 数组 (最多 8 张图片，每张 30MB)

响应

返回用于检查生成状态的任务 ID:

字段 类型 说明
id string 唯一任务标识符

Callback 格式

如果提供了 callback_url，生成完成时将发送 POST 请求。

成功响应: - 包含 status: "completed" - 包含 images 数组，含生成图像对象

失败响应: - 包含 status: "failed" - 包含 error 消息，描述失败原因

成功回调示例：

{
  "id": "281e5b0*********************f39b9",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/generated/image1.png"
    }
  ]
}

失败回调示例：

{
  "id": "281e5b0*********************f39b9",
  "status": "failed",
  "error": "Generation failed due to content policy violation"
}

生成图像 (专业版)

使用专业版模型创建图像生成任务：

curl -X POST "https://runapi.ai/api/v1/nano_banana/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-pro",
    "callback_url": "https://your-domain.com/api/callback",
    "prompt": "日落时分的宁静山景，天空呈现鲜艳的橙色和紫色",
    "aspect_ratio": "16:9",
    "output_resolution": "4k",
    "output_format": "png",
    "reference_image_urls": []
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/nano_banana/text_to_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'nano-banana-pro',
  callback_url: 'https://your-domain.com/api/callback',
  prompt: '日落时分的宁静山景，天空呈现鲜艳的橙色和紫色',
  aspect_ratio: '16:9',
  output_resolution: '4k',
  output_format: 'png',
  reference_image_urls: []
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/nano_banana/text_to_image'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'nano-banana-pro',
    'callback_url': 'https://your-domain.com/api/callback',
    'prompt': '日落时分的宁静山景，天空呈现鲜艳的橙色和紫色',
    'aspect_ratio': '16:9',
    'output_resolution': '4k',
    'output_format': 'png',
    'reference_image_urls': []
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'nano-banana-pro',
  callback_url: 'https://your-domain.com/api/callback',
  prompt: '日落时分的宁静山景，天空呈现鲜艳的橙色和紫色',
  aspect_ratio: '16:9',
  output_resolution: '4k',
  output_format: 'png',
  reference_image_urls: []
};

fetch('https://runapi.ai/api/v1/nano_banana/text_to_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

使用专业版 Nano Banana 模型创建新的图像生成任务，提供更高质量和更多功能。

HTTP 请求

POST https://runapi.ai/api/v1/nano_banana/text_to_image

请求参数

参数 类型 必需 说明
model string 是 使用的模型：nano-banana-pro 表示专业版
prompt string 是 期望图像的文本描述 (最多 5000 字符)
callback_url string 否 完成回调的 URL
aspect_ratio string 否 图像宽高比: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9, auto (默认: 1:1)
output_resolution string 否 图像输出分辨率: 1k, 2k, 4k (默认: 1k)
output_format string 否 输出格式: png, jpg (默认: png)
reference_image_urls array 否 参考图像 URL 数组 (最多 8 张图片，每张 30MB)

响应

返回用于检查生成状态的任务 ID:

字段 类型 说明
id string 唯一任务标识符

Callback 格式

如果提供了 callback_url，生成完成时将发送 POST 请求。

成功响应: - 包含 status: "completed" - 包含 images 数组，含生成图像对象

失败响应: - 包含 status: "failed" - 包含 error 消息，描述失败原因

成功回调示例：

{
  "id": "281e5b0*********************f39b9",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/generated/image1.png"
    }
  ]
}

失败回调示例：

{
  "id": "281e5b0*********************f39b9",
  "status": "failed",
  "error": "Generation failed due to content policy violation"
}

生成图像 (V2)

使用 V2 模型创建图像生成任务：

curl -X POST "https://runapi.ai/api/v1/nano_banana/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "callback_url": "https://your-domain.com/api/callback",
    "prompt": "漫画海报：戴着墨镜的酷炫香蕉英雄从科幻发射台跃起。六个画面：4K 山景、多语言翻译、Gemini 3 全息、相机控制、画幅组合、一致造型。标语：Nano Banana 2 现已上线 RunAPI。",
    "aspect_ratio": "auto",
    "output_resolution": "2k",
    "output_format": "jpg",
    "reference_image_urls": []
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/nano_banana/text_to_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'nano-banana-2',
  callback_url: 'https://your-domain.com/api/callback',
  prompt: '漫画海报：戴着墨镜的酷炫香蕉英雄从科幻发射台跃起。',
  aspect_ratio: 'auto',
  output_resolution: '2k',
  output_format: 'jpg',
  reference_image_urls: []
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/nano_banana/text_to_image'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'nano-banana-2',
    'callback_url': 'https://your-domain.com/api/callback',
    'prompt': '漫画海报：戴着墨镜的酷炫香蕉英雄从科幻发射台跃起。',
    'aspect_ratio': 'auto',
    'output_resolution': '2k',
    'output_format': 'jpg',
    'reference_image_urls': []
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'nano-banana-2',
  callback_url: 'https://your-domain.com/api/callback',
  prompt: '漫画海报：戴着墨镜的酷炫香蕉英雄从科幻发射台跃起。',
  aspect_ratio: 'auto',
  output_resolution: '2k',
  output_format: 'jpg',
  reference_image_urls: []
};

fetch('https://runapi.ai/api/v1/nano_banana/text_to_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

使用 Nano Banana V2 模型创建新的图像生成任务。相较基础版和专业版，V2 支持更长的提示词、更多的参考图片，以及更丰富的画幅比例。

HTTP 请求

POST https://runapi.ai/api/v1/nano_banana/text_to_image

请求参数

参数 类型 必填 描述
model string 是 模型名称：nano-banana-2
prompt string 是 图像文本描述（最多 20,000 字符）
callback_url string 否 完成回调 URL
aspect_ratio string 否 画幅比例：1:1、1:4、1:8、2:3、3:2、3:4、4:1、4:3、4:5、5:4、8:1、9:16、16:9、21:9、auto（默认：auto）
output_resolution string 否 图像输出分辨率：1k、2k、4k（默认：1k）
output_format string 否 输出格式：png、jpg（默认：jpg）
reference_image_urls array 否 参考图片 URL 数组（最多 14 张，jpeg/png/webp，每张 30MB）

价格

Nano Banana 2 价格

响应

返回任务 ID 以便查询生成状态：

字段 类型 描述
id string 任务唯一标识

回调格式

若提供 callback_url，生成完成后会发起 POST 请求：

成功响应： - 包含 status: "completed" - images 数组包含生成图像对象

失败响应： - 包含 status: "failed" - error 描述失败原因

获取生成状态

轮询生成结果：

curl "https://runapi.ai/api/v1/nano_banana/text_to_image/281e5b0f39b9" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

require 'net/http'
require 'uri'

task_id = '281e5b0f39b9'
uri = URI("https://runapi.ai/api/v1/nano_banana/text_to_image/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

import requests

task_id = '281e5b0f39b9'
url = f'https://runapi.ai/api/v1/nano_banana/text_to_image/{task_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = '281e5b0f39b9';

fetch(`https://runapi.ai/api/v1/nano_banana/text_to_image/${taskId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

处理中：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

已完成：

{
  "id": "281e5b0*********************f39b9",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/generated/image1.png"
    }
  ]
}

失败：

{
  "id": "281e5b0*********************f39b9",
  "status": "failed",
  "error": "Invalid prompt or content policy violation"
}

检索图像生成任务的状态和结果。

HTTP 请求

GET https://runapi.ai/api/v1/nano_banana/text_to_image/:id

URL 参数

参数 说明
id 创建请求返回的任务 ID

响应字段

字段 类型 说明
id string 唯一任务标识符
status string 任务状态: processing, completed, failed
images array 生成图像对象数组 (仅在状态为 completed 时存在)
error string 错误消息 (仅在状态为 failed 时存在)

状态值

编辑图像

创建图像编辑任务：

curl -X POST "https://runapi.ai/api/v1/nano_banana/edit_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-edit",
    "callback_url": "https://your-domain.com/api/callback",
    "prompt": "将这张照片变成角色手办。在它后面放置一个印有角色图像的盒子",
    "source_image_urls": [
      "https://cdn.runapi.ai/public/samples/image.jpg"
    ],
    "output_format": "png",
    "aspect_ratio": "1:1"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/nano_banana/edit_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'nano-banana-edit',
  callback_url: 'https://your-domain.com/api/callback',
  prompt: '将这张照片变成角色手办。在它后面放置一个印有角色图像的盒子',
  source_image_urls: [
    'https://cdn.runapi.ai/public/samples/image.jpg'
  ],
  output_format: 'png',
  aspect_ratio: '1:1'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/nano_banana/edit_image'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'nano-banana-edit',
    'callback_url': 'https://your-domain.com/api/callback',
    'prompt': '将这张照片变成角色手办。在它后面放置一个印有角色图像的盒子',
    'source_image_urls': [
        'https://cdn.runapi.ai/public/samples/image.jpg'
    ],
    'output_format': 'png',
    'aspect_ratio': '1:1'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'nano-banana-edit',
  callback_url: 'https://your-domain.com/api/callback',
  prompt: '将这张照片变成角色手办。在它后面放置一个印有角色图像的盒子',
  source_image_urls: [
    'https://cdn.runapi.ai/public/samples/image.jpg'
  ],
  output_format: 'png',
  aspect_ratio: '1:1'
};

fetch('https://runapi.ai/api/v1/nano_banana/edit_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

创建图像编辑任务，根据文本提示转换和修改图像。

HTTP 请求

POST https://runapi.ai/api/v1/nano_banana/edit_image

请求参数

参数 类型 必需 说明
model string 是 使用的模型：nano-banana-edit
prompt string 是 期望编辑的文本描述 (最多 5000 字符)
source_image_urls array 是 输入图像 URL 数组 (最多 10 张图片，每张 10MB)
callback_url string 否 完成回调的 URL
output_format string 否 输出格式: png, jpeg (默认: png)
aspect_ratio string 否 输出宽高比: 1:1, 9:16, 16:9, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9, auto (默认: 1:1)

响应

返回用于检查编辑状态的任务 ID:

字段 类型 说明
id string 唯一任务标识符

Callback 格式

如果提供了 callback_url，编辑完成时将发送 POST 请求。

成功响应: - 包含 status: "completed" - 包含 images 数组，含编辑后图像对象

失败响应: - 包含 status: "failed" - 包含 error 消息，描述失败原因

成功回调示例：

{
  "id": "281e5b0*********************f39b9",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/edited/image1.webp"
    }
  ]
}

失败回调示例：

{
  "id": "281e5b0*********************f39b9",
  "status": "failed",
  "error": "Failed to fetch the image"
}

获取编辑状态

轮询编辑结果：

curl "https://runapi.ai/api/v1/nano_banana/edit_image/281e5b0f39b9" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

task_id = '281e5b0f39b9'
uri = URI("https://runapi.ai/api/v1/nano_banana/edit_image/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

task_id = '281e5b0f39b9'
url = f'https://runapi.ai/api/v1/nano_banana/edit_image/{task_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = '281e5b0f39b9';

fetch(`https://runapi.ai/api/v1/nano_banana/edit_image/${taskId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

处理中：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

已完成：

{
  "id": "281e5b0*********************f39b9",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/edited/image1.webp"
    }
  ]
}

失败：

{
  "id": "281e5b0*********************f39b9",
  "status": "failed",
  "error": "Failed to fetch the image"
}

检索图像编辑任务的状态和结果。

HTTP 请求

GET https://runapi.ai/api/v1/nano_banana/edit_image/:id

URL 参数

参数 说明
id 编辑任务的 ID

响应字段

字段 类型 说明
id string 唯一任务标识符
status string 任务状态: processing, completed, failed
images array 编辑后图像对象数组 (仅在状态为 completed 时存在)
error string 错误消息 (仅在状态为 failed 时存在)

Imagen 4

Imagen 4 支持文生图和 Pro remix image 任务。

模型 模式 价格
imagen-4 文生图 价格
imagen-4-fast 文生图 价格
imagen-4-ultra 文生图 价格
imagen-4-pro-remix-image Pro remix image 价格

创建 Imagen 4 任务

curl -X POST "https://runapi.ai/api/v1/imagen_4/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"imagen-4-fast","prompt":"A warm editorial photo of a glass studio","aspect_ratio":"16:9"}'

响应：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

创建新的 Imagen 4 图片任务。

参数

参数 类型 必填 说明
model string 是 imagen-4、imagen-4-fast 或 imagen-4-ultra
prompt string 是 文本提示词；最多 5000 字符
negative_prompt string 否 Imagen 4 文生图模型中需要弱化的内容
aspect_ratio string 否 输出比例；1:1、16:9、9:16、3:4 或 4:3
output_count number 否 imagen-4-fast 的生成图片数量：1、2、3 或 4
seed number 否 用于复现结果的随机种子
callback_url string 否 任务完成时通知的 Webhook URL

创建 Pro Remix Image

curl -X POST "https://runapi.ai/api/v1/imagen_4/remix_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"imagen-4-pro-remix-image","prompt":"Restyle the reference image as a clean editorial poster","source_image_urls":["https://upload.wikimedia.org/wikipedia/commons/a/a9/Example.jpg"],"aspect_ratio":"auto","output_resolution":"2k","output_format":"png"}'

创建提示词驱动的 remix image 任务。

参数

参数 类型 必填 说明
model string 是 imagen-4-pro-remix-image
prompt string 是 文本提示词；最多 10000 字符
source_image_urls array 是 公网图片 URL，最多 8 张
aspect_ratio string 否 输出比例；1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 或 auto
output_resolution string 否 输出分辨率：1k、2k 或 4k
output_format string 否 输出格式：png 或 jpg
callback_url string 否 任务完成时通知的 Webhook URL

查询 Imagen 4 任务

curl "https://runapi.ai/api/v1/imagen_4/text_to_image/TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

完成响应：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/generated/image.png"
    }
  ]
}

Flux Kontext

Flux Kontext 是 Black Forest Labs 的先进图像生成与编辑模型。它通过一个文生图端点支持纯提示词生成和源图编辑。

模型

模型 类型 价格
flux-kontext-pro 标准质量 价格
flux-kontext-max 增强质量 价格

Flux Kontext 端点概览

任务 端点 方法
生成 / 编辑图像 生成图像 POST
检查状态 获取生成状态 GET

生成图像

文生图：

curl -X POST "https://runapi.ai/api/v1/flux_kontext/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-kontext-pro",
    "prompt": "日落时分的未来城市，飞行汽车和霓虹灯光",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/flux_kontext/text_to_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'flux-kontext-pro',
  prompt: '日落时分的未来城市，飞行汽车和霓虹灯光',
  aspect_ratio: '16:9',
  output_format: 'png'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/flux_kontext/text_to_image'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'flux-kontext-pro',
    'prompt': '日落时分的未来城市，飞行汽车和霓虹灯光',
    'aspect_ratio': '16:9',
    'output_format': 'png'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'flux-kontext-pro',
  prompt: '日落时分的未来城市，飞行汽车和霓虹灯光',
  aspect_ratio: '16:9',
  output_format: 'png'
};

fetch('https://runapi.ai/api/v1/flux_kontext/text_to_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

使用源图编辑：

curl -X POST "https://runapi.ai/api/v1/flux_kontext/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-kontext-pro",
    "prompt": "将背景更换为热带海滩",
    "source_image_url": "https://cdn.runapi.ai/public/samples/image.jpg",
    "safety_tolerance": 2
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/flux_kontext/text_to_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'flux-kontext-pro',
  prompt: '将背景更换为热带海滩',
  source_image_url: 'https://cdn.runapi.ai/public/samples/image.jpg',
  safety_tolerance: 2
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/flux_kontext/text_to_image'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'flux-kontext-pro',
    'prompt': '将背景更换为热带海滩',
    'source_image_url': 'https://cdn.runapi.ai/public/samples/image.jpg',
    'safety_tolerance': 2
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'flux-kontext-pro',
  prompt: '将背景更换为热带海滩',
  source_image_url: 'https://cdn.runapi.ai/public/samples/image.jpg',
  safety_tolerance: 2
};

fetch('https://runapi.ai/api/v1/flux_kontext/text_to_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

创建新的图像生成或编辑任务。提供 source_image_url 时，模型会编辑该源图；否则从文本生成图像。

HTTP 请求

POST https://runapi.ai/api/v1/flux_kontext/text_to_image

请求参数

参数 类型 必需 说明
model string 是 使用的模型：flux-kontext-pro 或 flux-kontext-max
prompt string 是 期望图像或编辑的文本描述
aspect_ratio string 否 输出宽高比：21:9、16:9、4:3、1:1、3:4、9:16（默认：1:1）
output_format string 否 输出格式：jpeg、png（默认：jpeg）
source_image_url string 否 编辑模式下的源图像 URL
enable_translation boolean 否 自动翻译非英语提示词
enable_prompt_expansion boolean 否 自动扩展提示词以添加更多细节
safety_tolerance integer 否 内容安全级别：生成模式 0-6，编辑模式 0-2（数值越低越严格）
callback_url string 否 完成回调的 URL
watermark string 否 生成图像的水印标识

响应

返回用于检查生成状态的任务 ID：

字段 类型 说明
id string 唯一任务标识符
status string 初始状态：processing

Callback 格式

如果提供了 callback_url，生成完成时将发送 POST 请求。

成功响应: - 包含 status: "completed" - 包含 images 数组，含生成的图像 URL

失败响应: - 包含 status: "failed" - 包含 error 消息，描述失败原因

成功回调示例：

{
  "id": "281e5b0*********************f39b9",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/generated/image1.png",
      "origin_url": "https://file.runapi.ai/origin/image1.png"
    }
  ]
}

失败回调示例：

{
  "id": "281e5b0*********************f39b9",
  "status": "failed",
  "error": "Generation failed due to content policy violation"
}

获取生成状态

轮询生成结果：

curl "https://runapi.ai/api/v1/flux_kontext/text_to_image/281e5b0f39b9" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

require 'net/http'
require 'uri'

task_id = '281e5b0f39b9'
uri = URI("https://runapi.ai/api/v1/flux_kontext/text_to_image/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

import requests

task_id = '281e5b0f39b9'
url = f'https://runapi.ai/api/v1/flux_kontext/text_to_image/{task_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = '281e5b0f39b9';

fetch(`https://runapi.ai/api/v1/flux_kontext/text_to_image/${taskId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

处理中：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

已完成：

{
  "id": "281e5b0*********************f39b9",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/generated/image1.png",
      "origin_url": "https://file.runapi.ai/origin/image1.png"
    }
  ]
}

失败：

{
  "id": "281e5b0*********************f39b9",
  "status": "failed",
  "error": "Generation failed due to content policy violation"
}

检索图像生成任务的状态和结果。

HTTP 请求

GET https://runapi.ai/api/v1/flux_kontext/text_to_image/:id

URL 参数

参数 说明
id 创建请求返回的任务 ID

响应字段

字段 类型 说明
id string 唯一任务标识符
status string 任务状态：processing、completed、failed
images array 图像对象数组（仅在状态为 completed 时存在）
images[].url string 临时生成图片 URL，有效期为 7 天
images[].origin_url string 原始高分辨率 URL，临时链接，有效期为 7 天
error string 错误消息（仅在状态为 failed 时存在）

状态值

Flux 2

Flux 2 通过独立的文生图和 remix-image 端点提供 Black Forest Labs 图像生成能力。文生图用于纯提示词生成，remix-image 用于让一张或多张源图引导结果。

模型

模型 端点
flux-2-pro-text-to-image 文生图
flux-2-flex-text-to-image 文生图
flux-2-pro-remix-image Remix image
flux-2-flex-remix-image Remix image

Flux 2 端点概览

任务 端点 方法
创建文生图任务 创建文生图 POST
获取文生图状态 获取文生图状态 GET
创建 remix-image 任务 创建 Remix Image POST
获取 remix-image 状态 获取 Remix Image 状态 GET

创建文生图

文生图：

curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "一位宇航员漂浮在太空中的逼真肖像，背景是地球",
    "aspect_ratio": "16:9",
    "output_resolution": "2k"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/flux_2/text_to_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'flux-2-pro-text-to-image',
  prompt: '一位宇航员漂浮在太空中的逼真肖像，背景是地球',
  aspect_ratio: '16:9',
  output_resolution: '2k'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/flux_2/text_to_image'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'flux-2-pro-text-to-image',
    'prompt': '一位宇航员漂浮在太空中的逼真肖像，背景是地球',
    'aspect_ratio': '16:9',
    'output_resolution': '2k'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'flux-2-pro-text-to-image',
  prompt: '一位宇航员漂浮在太空中的逼真肖像，背景是地球',
  aspect_ratio: '16:9',
  output_resolution: '2k'
};

fetch('https://runapi.ai/api/v1/flux_2/text_to_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

创建一个基于提示词的文生图任务。

HTTP 请求

POST https://runapi.ai/api/v1/flux_2/text_to_image

请求参数

参数 类型 必需 说明
model string 是 flux-2-pro-text-to-image 或 flux-2-flex-text-to-image
prompt string 是 期望图像的文本描述（3-5000 字符）
aspect_ratio string 否 1:1、4:3、3:4、16:9、9:16、3:2 或 2:3
output_resolution string 否 输出图像分辨率：1k 或 2k
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 完成回调的 URL

响应

返回用于检查任务状态的任务 ID：

字段 类型 说明
id string 唯一任务标识符
status string 初始状态：processing

获取文生图状态

轮询任务结果：

curl "https://runapi.ai/api/v1/flux_2/text_to_image/281e5b0f39b9" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

require 'net/http'
require 'uri'

task_id = '281e5b0f39b9'
uri = URI("https://runapi.ai/api/v1/flux_2/text_to_image/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

import requests

task_id = '281e5b0f39b9'
url = f'https://runapi.ai/api/v1/flux_2/text_to_image/{task_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = '281e5b0f39b9';

fetch(`https://runapi.ai/api/v1/flux_2/text_to_image/${taskId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

检索文生图任务的状态和结果。

HTTP 请求

GET https://runapi.ai/api/v1/flux_2/text_to_image/:id

创建 Remix Image

Remix-image 请求：

curl -X POST "https://runapi.ai/api/v1/flux_2/remix_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-remix-image",
    "prompt": "将这张照片转换为暖色调的油画风格",
    "source_image_urls": [
      "https://cdn.runapi.ai/public/samples/image.jpg"
    ],
    "aspect_ratio": "auto"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/flux_2/remix_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'flux-2-pro-remix-image',
  prompt: '将这张照片转换为暖色调的油画风格',
  source_image_urls: [
    'https://cdn.runapi.ai/public/samples/image.jpg'
  ],
  aspect_ratio: 'auto'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/flux_2/remix_image'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'flux-2-pro-remix-image',
    'prompt': '将这张照片转换为暖色调的油画风格',
    'source_image_urls': [
        'https://cdn.runapi.ai/public/samples/image.jpg'
    ],
    'aspect_ratio': 'auto'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'flux-2-pro-remix-image',
  prompt: '将这张照片转换为暖色调的油画风格',
  source_image_urls: [
    'https://cdn.runapi.ai/public/samples/image.jpg'
  ],
  aspect_ratio: 'auto'
};

fetch('https://runapi.ai/api/v1/flux_2/remix_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

创建一个由源图和提示词共同引导的 remix 任务。

HTTP 请求

POST https://runapi.ai/api/v1/flux_2/remix_image

请求参数

参数 类型 必需 说明
model string 是 flux-2-pro-remix-image 或 flux-2-flex-remix-image
prompt string 是 Remix 指令（3-5000 字符）
source_image_urls array 是 源图 URL（1-8 张图片）
aspect_ratio string 否 1:1、4:3、3:4、16:9、9:16、3:2、2:3 或 auto
output_resolution string 否 输出图像分辨率：1k 或 2k
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 完成回调的 URL

获取 Remix Image 状态

轮询 remix 结果：

curl "https://runapi.ai/api/v1/flux_2/remix_image/281e5b0f39b9" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

require 'net/http'
require 'uri'

task_id = '281e5b0f39b9'
uri = URI("https://runapi.ai/api/v1/flux_2/remix_image/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

import requests

task_id = '281e5b0f39b9'
url = f'https://runapi.ai/api/v1/flux_2/remix_image/{task_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = '281e5b0f39b9';

fetch(`https://runapi.ai/api/v1/flux_2/remix_image/${taskId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

检索 remix-image 任务的状态和结果。

HTTP 请求

GET https://runapi.ai/api/v1/flux_2/remix_image/:id

响应字段

字段 类型 说明
id string 唯一任务标识符
status string 任务状态：processing、completed、failed
images array 图像对象数组（仅在状态为 completed 时存在）
images[].url string 临时生成图片 URL，有效期为 7 天
error string 错误消息（仅在状态为 failed 时存在）

Qwen 2

Qwen 2 支持文生图、提示词图像 remix 和提示词图像编辑。所有任务都是异步任务，会返回可轮询或通过 webhook 接收的任务 ID。

模型

模型 能力 价格
qwen-2-text-to-image 文生图 价格
qwen-2-remix-image 图像 remix 价格
qwen-2-edit-image 图像编辑 价格

Qwen 2 端点

操作 端点
创建文生图任务 POST /api/v1/qwen_2/text_to_image
查询文生图任务 GET /api/v1/qwen_2/text_to_image/:id
创建图像 remix 任务 POST /api/v1/qwen_2/remix_image
查询图像 remix 任务 GET /api/v1/qwen_2/remix_image/:id
创建图像编辑任务 POST /api/v1/qwen_2/edit_image
查询图像编辑任务 GET /api/v1/qwen_2/edit_image/:id

创建文生图

curl -X POST "https://runapi.ai/api/v1/qwen_2/text_to_image" \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-2-text-to-image",
    "prompt": "A cinematic glass city at sunrise, high detail",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }'

POST https://runapi.ai/api/v1/qwen_2/text_to_image

参数 类型 必需 描述
model string 是 必须为 qwen-2-text-to-image
prompt string 是 文本提示词，最多 800 字符
aspect_ratio string 否 1:1、3:4、4:3、9:16 或 16:9；默认 16:9
seed integer 否 用于复现结果的随机种子
output_format string 否 png 或 jpeg；默认 png
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 用于接收完成通知的 webhook URL

创建图像 Remix

curl -X POST "https://runapi.ai/api/v1/qwen_2/remix_image" \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-2-remix-image",
    "prompt": "Turn this scene into a soft watercolor illustration",
    "source_image_url": "https://cdn.runapi.ai/public/samples/image.jpg",
    "strength": 0.8,
    "output_format": "png"
  }'

POST https://runapi.ai/api/v1/qwen_2/remix_image

参数 类型 必需 描述
model string 是 必须为 qwen-2-remix-image
prompt string 是 Remix 提示词，最多 5000 字符
source_image_url string 是 源图 URL；支持 JPEG、PNG 和 WebP，最大 10 MB
strength number 否 去噪强度，范围 0 到 1；默认 0.8
output_format string 否 png 或 jpeg；默认 png
acceleration string 否 none、regular 或 high；默认 none
negative_prompt string 否 反向提示词，最多 500 字符
seed integer 否 用于复现结果的随机种子
num_inference_steps integer 否 推理步数，范围 2 到 250；默认 30
guidance_scale number 否 提示词遵循强度，范围 0 到 20；默认 2.5
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 用于接收完成通知的 webhook URL

创建图像编辑

curl -X POST "https://runapi.ai/api/v1/qwen_2/edit_image" \
  -H "Authorization: Bearer $RUNAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-2-edit-image",
    "prompt": "Replace the background with a neon-lit city skyline",
    "source_image_url": "https://cdn.runapi.ai/public/samples/image.jpg",
    "aspect_ratio": "16:9",
    "output_format": "png"
  }'

POST https://runapi.ai/api/v1/qwen_2/edit_image

参数 类型 必需 描述
model string 是 必须为 qwen-2-edit-image
prompt string 是 编辑指令，最多 800 字符
source_image_url string 是 源图 URL；支持 JPEG、PNG 和 WebP，最大 10 MB
aspect_ratio string 否 1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9, or 21:9
output_format string 否 jpeg 或 png；默认 png
seed integer 否 用于复现结果的随机种子
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 用于接收完成通知的 webhook URL

响应

创建端点返回 202 Accepted：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

轮询和 webhook 响应使用相同结构：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/tools/example/result.png"
    }
  ]
}

Recraft

RunAPI 上的 Recraft 提供两个图像后处理能力：图像超分和背景移除。

模型

模型 类型 积分
recraft-crisp-upscale 图像超分 1
recraft-remove-background 背景移除 1

Recraft 端点

任务 端点 方法
图像超分 Upscale Image POST
背景移除 Remove Background POST
查询任务状态 Get Recraft Task Status GET

Upscale Recraft Image

对图片做超分处理：

curl -X POST "https://runapi.ai/api/v1/recraft/upscale_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft-crisp-upscale",
    "source_image_url": "https://cdn.runapi.ai/public/samples/upscale.jpg"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/recraft/upscale_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'recraft-crisp-upscale',
  source_image_url: 'https://cdn.runapi.ai/public/samples/upscale.jpg'
}.to_json

response = http.request(request)
puts response.body

import requests

response = requests.post(
    'https://runapi.ai/api/v1/recraft/upscale_image',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'model': 'recraft-crisp-upscale',
        'source_image_url': 'https://cdn.runapi.ai/public/samples/upscale.jpg'
    }
)
print(response.json())

fetch('https://runapi.ai/api/v1/recraft/upscale_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'recraft-crisp-upscale',
    source_image_url: 'https://cdn.runapi.ai/public/samples/upscale.jpg'
  })
})
.then(res => res.json())
.then(data => console.log(data));

HTTP 202 - 已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/recraft/upscale_image

请求参数

参数 类型 必填 说明
model string 是 必须为 recraft-crisp-upscale
source_image_url string 是 源图 URL
callback_url string 否 完成回调 URL

Remove Recraft Background

移除图片背景：

curl -X POST "https://runapi.ai/api/v1/recraft/remove_background" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft-remove-background",
    "source_image_url": "https://cdn.runapi.ai/public/samples/remove-bg.jpg"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/recraft/remove_background')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'recraft-remove-background',
  source_image_url: 'https://cdn.runapi.ai/public/samples/remove-bg.jpg'
}.to_json

response = http.request(request)
puts response.body

import requests

response = requests.post(
    'https://runapi.ai/api/v1/recraft/remove_background',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'model': 'recraft-remove-background',
        'source_image_url': 'https://cdn.runapi.ai/public/samples/remove-bg.jpg'
    }
)
print(response.json())

fetch('https://runapi.ai/api/v1/recraft/remove_background', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'recraft-remove-background',
    source_image_url: 'https://cdn.runapi.ai/public/samples/remove-bg.jpg'
  })
})
.then(res => res.json())
.then(data => console.log(data));

HTTP 202 - 已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/recraft/remove_background

请求参数

参数 类型 必填 说明
model string 是 必须为 recraft-remove-background
source_image_url string 是 源图 URL
callback_url string 否 完成回调 URL

Get Recraft Task Status

根据你创建任务时使用的端点，调用对应的 GET 端点查询状态：

创建端点 查询端点
POST /api/v1/recraft/upscale_image GET /api/v1/recraft/upscale_image/:id
POST /api/v1/recraft/remove_background GET /api/v1/recraft/remove_background/:id

查询超分任务：

curl "https://runapi.ai/api/v1/recraft/upscale_image/281e5b0f39b9" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "id": "281e5b0*********************f39b9",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/recraft/result.png"
    }
  ]
}

返回字段

字段 类型 说明
id string 唯一任务 ID
status string 任务状态：processing、completed、failed
images array 任务完成时返回的结果图片对象
images[].url string 临时结果图片 URL，有效期为 7 天
error string 任务失败时的错误信息

Z-Image

Z-Image 根据文本提示生成图片，支持五种宽高比和异步回调。

模型

模型 类型 积分
z-image 文生图 1

Z-Image 端点

任务 端点 方法
生成图片 生成图片 POST
查询状态 查询文生图状态 GET

生成图片

生成一张图片：

curl -X POST "https://runapi.ai/api/v1/z_image/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "prompt": "Generate a photorealistic image of a cafe terrace in Paris on a crisp spring morning",
    "aspect_ratio": "1:1",
    "enable_safety_checker": true
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/z_image/text_to_image')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'z-image',
  prompt: 'Generate a photorealistic image of a cafe terrace in Paris on a crisp spring morning',
  aspect_ratio: '1:1',
  enable_safety_checker: true
}.to_json

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.body

import requests

response = requests.post(
    'https://runapi.ai/api/v1/z_image/text_to_image',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'model': 'z-image',
        'prompt': 'Generate a photorealistic image of a cafe terrace in Paris on a crisp spring morning',
        'aspect_ratio': '1:1',
        'enable_safety_checker': True
    }
)
print(response.json())

fetch('https://runapi.ai/api/v1/z_image/text_to_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'z-image',
    prompt: 'Generate a photorealistic image of a cafe terrace in Paris on a crisp spring morning',
    aspect_ratio: '1:1',
    enable_safety_checker: true
  })
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "281e5b0*********************f39b9",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/z_image/text_to_image

请求参数

参数 类型 必填 说明
model string 是 必须为 z-image
prompt string 是 图片描述，最多 1000 个字符
aspect_ratio string 是 输出宽高比：1:1、4:3、3:4、16:9、9:16
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 完成回调 URL

查询文生图状态

轮询生成结果：

curl "https://runapi.ai/api/v1/z_image/text_to_image/281e5b0f39b9" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

HTTP 请求

GET https://runapi.ai/api/v1/z_image/text_to_image/{id}

响应示例

{
  "id": "281e5b0*********************f39b9",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/generated/image1.png"
    }
  ]
}

Ideogram V3

Ideogram V3 是 RunAPI 集成的 Ideogram 图像生成家族，覆盖文生图、角色参考生成、局部重绘（Edit）、图像重混（Remix）和 Reframe 构图调整。

模型

模型 类型 价格
ideogram-v3-text-to-image 文生图 价格
ideogram-v3-edit 局部重绘 价格
ideogram-v3-remix 图像重混 价格
ideogram-v3-character 角色参考文生图 价格
ideogram-v3-character-edit 角色参考局部重绘 价格
ideogram-v3-character-remix 角色参考重混 价格
ideogram-v3-reframe 图像 Reframe 价格

Ideogram V3 接口

任务 接口 方法
文生图 创建文生图 POST
查询文生图状态 获取文生图状态 GET
图像局部重绘 创建 Edit POST
查询 Edit 状态 获取 Edit 状态 GET
图像 Remix 创建 Remix POST
查询 Remix 状态 获取 Remix 状态 GET
图像 Reframe 创建 Reframe POST
查询 Reframe 状态 获取 Reframe 状态 GET

Create Ideogram V3 Text-to-Image

curl -X POST "https://runapi.ai/api/v1/ideogram_v3/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-text-to-image",
    "prompt": "霓虹芦苇映照的黄昏湖景",
    "rendering_speed": "balanced",
    "style": "realistic",
    "aspect_ratio": "1:1"
  }'

POST https://runapi.ai/api/v1/ideogram_v3/text_to_image

参数 类型 必填 说明
model string 是 必须为 ideogram-v3-text-to-image
prompt string 是 最多 5000 字符
reference_image_urls array ideogram-v3-character 必填 角色参考图 URL；仅使用第一张，JPEG/PNG/WEBP，总大小最大 10 MB
callback_url string 否 完成回调 Webhook 地址
rendering_speed string 否 turbo、balanced（默认）、quality
style string 否 auto、general、realistic、design；ideogram-v3-character 支持 auto、realistic、fiction
enable_prompt_expansion boolean 否 是否使用 MagicPrompt 扩写提示词
aspect_ratio string 否 1:1、3:4、9:16、4:3、16:9
output_count number 否 1、2、3、4
seed integer 否 随机种子
negative_prompt string 否 最多 5000 字符，排除元素

在此接口使用 model: "ideogram-v3-character" 可进行角色参考生成。Character 请求必须传 reference_image_urls，并可使用 style: "fiction" 与 output_count。

响应

{
  "id": "281e5b0f39b9",
  "status": "processing"
}

Get Ideogram V3 Text-to-Image Status

curl "https://runapi.ai/api/v1/ideogram_v3/text_to_image/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET https://runapi.ai/api/v1/ideogram_v3/text_to_image/:id

成功响应

{
  "id": "281e5b0f39b9",
  "status": "completed",
  "images": [
    { "url": "https://file.runapi.ai/ideogram/result.png" }
  ]
}

失败响应

{
  "id": "281e5b0f39b9",
  "status": "failed",
  "error": "Prompt rejected"
}

Create Ideogram V3 Edit

curl -X POST "https://runapi.ai/api/v1/ideogram_v3/edit_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-edit",
    "prompt": "戴牛仔帽的狗",
    "source_image_url": "https://cdn.runapi.ai/public/samples/image.jpg",
    "mask_url": "https://cdn.runapi.ai/public/samples/mask.png",
    "rendering_speed": "balanced"
  }'

POST https://runapi.ai/api/v1/ideogram_v3/edit_image

参数 类型 必填 说明
model string 是 必须为 ideogram-v3-edit
prompt string 是 用于填充遮罩区域的描述，最多 5000 字符
source_image_url string 是 原图 URL，支持 JPEG/PNG/WEBP，最大 10 MB
mask_url string 是 遮罩 URL，需与原图尺寸一致
reference_image_urls array ideogram-v3-character-edit 必填 角色参考图 URL；仅使用第一张，JPEG/PNG/WEBP，总大小最大 10 MB
callback_url string 否 完成回调 Webhook 地址
rendering_speed string 否 turbo、balanced（默认）、quality
style string 否 仅 ideogram-v3-character-edit 支持：auto、realistic、fiction
enable_prompt_expansion boolean 否 是否使用 MagicPrompt 扩写提示词
output_count number 否 1、2、3、4
seed integer 否 随机种子

在此接口使用 model: "ideogram-v3-character-edit" 可进行角色参考局部重绘。Character Edit 请求必须传 reference_image_urls。

响应

{
  "id": "281e5b0f39b9",
  "status": "processing"
}

Get Ideogram V3 Edit Status

curl "https://runapi.ai/api/v1/ideogram_v3/edit_image/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET https://runapi.ai/api/v1/ideogram_v3/edit_image/:id

响应结构与 文生图状态查询 一致。

Create Ideogram V3 Remix

curl -X POST "https://runapi.ai/api/v1/ideogram_v3/remix_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-remix",
    "prompt": "把立方体变成球",
    "source_image_url": "https://cdn.runapi.ai/public/samples/image.jpg",
    "rendering_speed": "balanced",
    "strength": 0.8,
    "output_count": 1
  }'

POST https://runapi.ai/api/v1/ideogram_v3/remix_image

参数 类型 必填 说明
model string 是 必须为 ideogram-v3-remix
prompt string 是 最多 5000 字符
source_image_url string 是 原图 URL，JPEG/PNG/WEBP，最大 10 MB
reference_image_urls array ideogram-v3-character-remix 必填 角色参考图 URL；仅使用第一张，JPEG/PNG/WEBP，总大小最大 10 MB
callback_url string 否 完成回调 Webhook 地址
rendering_speed string 否 turbo、balanced（默认）、quality
style string 否 auto、general、realistic、design；ideogram-v3-character-remix 支持 auto、realistic、fiction
enable_prompt_expansion boolean 否 是否使用 MagicPrompt 扩写提示词
aspect_ratio string 否 1:1、3:4、9:16、4:3、16:9
output_count number 否 1、2、3、4
seed integer 否 随机种子
strength number 否 ideogram-v3-remix 为 0.01–1；ideogram-v3-character-remix 为 0.1–1
negative_prompt string 否 ideogram-v3-remix 最多 5000 字符；ideogram-v3-character-remix 最多 500 字符
style_reference_image_urls array 否 仅 ideogram-v3-character-remix 支持：风格参考图 URL
reference_mask_urls array 否 仅 ideogram-v3-character-remix 支持：角色参考图遮罩；没有 reference_image_urls 时会被忽略

在此接口使用 model: "ideogram-v3-character-remix" 可进行角色参考重混。Character Remix 请求必须传 reference_image_urls。

响应

{
  "id": "281e5b0f39b9",
  "status": "processing"
}

Get Ideogram V3 Remix Status

curl "https://runapi.ai/api/v1/ideogram_v3/remix_image/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET https://runapi.ai/api/v1/ideogram_v3/remix_image/:id

响应结构与 文生图状态查询 一致。

Create Ideogram V3 Reframe

curl -X POST "https://runapi.ai/api/v1/ideogram_v3/reframe_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ideogram-v3-reframe",
    "source_image_url": "https://cdn.runapi.ai/public/samples/image.jpg",
    "aspect_ratio": "3:4",
    "rendering_speed": "balanced",
    "style": "auto",
    "output_count": 1
  }'

POST https://runapi.ai/api/v1/ideogram_v3/reframe_image

参数 类型 必填 说明
model string 是 必须为 ideogram-v3-reframe
source_image_url string 是 原图 URL，JPEG/PNG/WEBP，最大 10 MB
aspect_ratio string 是 1:1、3:4、9:16、4:3、16:9
callback_url string 否 完成回调 Webhook 地址
rendering_speed string 否 turbo、balanced（默认）、quality
style string 否 auto、general、realistic、design
output_count number 否 1、2、3、4
seed integer 否 随机种子

响应

{
  "id": "281e5b0f39b9",
  "status": "processing"
}

Get Ideogram V3 Reframe Status

curl "https://runapi.ai/api/v1/ideogram_v3/reframe_image/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET https://runapi.ai/api/v1/ideogram_v3/reframe_image/:id

响应结构与 文生图状态查询 一致。

ElevenLabs

RunAPI 上的 ElevenLabs 提供文本转语音、多角色对白生成、音效生成、语音转文本和音频人声隔离，全部使用统一的异步任务接口。

ElevenLabs 端点概览

任务 端点 模型
创建语音 创建 ElevenLabs 语音 text-to-speech-turbo-v2.5、text-to-speech-multilingual-v2
查询语音 查询 ElevenLabs 语音 -
创建对白 创建 ElevenLabs 对白 text-to-dialogue-v3
查询对白 查询 ElevenLabs 对白 -
创建音效 创建 ElevenLabs 音效 sound-effect-v2
查询音效 查询 ElevenLabs 音效 -
创建转写 创建 ElevenLabs 转写 speech-to-text
查询转写 查询 ElevenLabs 转写 -
创建人声隔离 创建 ElevenLabs 人声隔离 audio-isolation
查询人声隔离 查询 ElevenLabs 人声隔离 -

创建 ElevenLabs 语音

curl -X POST "https://runapi.ai/api/v1/elevenlabs/text_to_speech" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-to-speech-turbo-v2.5",
    "text": "Hello from RunAPI",
    "voice": "EkK5I93UQWFDigLMpZcX"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}
参数 类型 必填 说明
model string 是 text-to-speech-turbo-v2.5 或 text-to-speech-multilingual-v2
text string 是 语音文本，最长 5000 字符
voice string 条件必填 语音名称或 voice ID；多语言模型必填，Turbo 可选。Turbo 省略时默认使用 EkK5I93UQWFDigLMpZcX。
callback_url string 否 HTTPS 回调地址
stability number 否 0-1
similarity_boost number 否 0-1
style number 否 0-1
speed number 否 0.7-1.2
timestamps boolean 否 返回词级时间戳
previous_text string 否 前文上下文
next_text string 否 后文上下文
language_code string 否 语言提示

查询 ElevenLabs 语音

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "audios": [
    { "url": "https://file.runapi.ai/audio.mp3" }
  ]
}

创建 ElevenLabs 对白

curl -X POST "https://runapi.ai/api/v1/elevenlabs/text_to_dialogue" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dialogue": [
      { "text": "你好", "voice": "Adam" },
      { "text": "欢迎使用 RunAPI", "voice": "Brian" }
    ],
    "stability": 0.5
  }'
参数 类型 必填 说明
dialogue array 是 对白数组，每项包含 text 与 voice；总文本最长 5000 字符
stability number 否 0、0.5 或 1
language_code string 否 语言提示
callback_url string 否 HTTPS 回调地址

查询 ElevenLabs 对白

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "audios": [
    { "url": "https://tempfile.runapi.ai/dialogue.mp3" }
  ]
}

创建 ElevenLabs 音效

curl -X POST "https://runapi.ai/api/v1/elevenlabs/text_to_sound" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "雷声与大雨",
    "output_format": "mp3_44100_128"
  }'
参数 类型 必填 说明
text string 是 音效提示词，最长 5000 字符
loop boolean 否 是否生成可循环音效
duration_seconds number 否 0.5-22
prompt_influence number 否 0-1
output_format string 否 输出编码与码率
callback_url string 否 HTTPS 回调地址

查询 ElevenLabs 音效

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "audios": [
    { "url": "https://file.runapi.ai/sound-effect.mp3" }
  ]
}

创建 ElevenLabs 转写

curl -X POST "https://runapi.ai/api/v1/elevenlabs/speech_to_text" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_audio_url": "https://cdn.runapi.ai/public/samples/voice.mp3",
    "diarize": true
  }'
参数 类型 必填 说明
source_audio_url string 是 源音频 URL
language_code string 否 语言提示
tag_audio_events boolean 否 标记掌声、笑声等音频事件
diarize boolean 否 标注说话人
callback_url string 否 HTTPS 回调地址

查询 ElevenLabs 转写

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "text": "Hello from ElevenLabs"
}

创建 ElevenLabs 人声隔离

curl -X POST "https://runapi.ai/api/v1/elevenlabs/isolate_audio" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_audio_url": "https://cdn.runapi.ai/public/samples/voice.mp3"
  }'
参数 类型 必填 说明
source_audio_url string 是 源音频 URL
callback_url string 否 HTTPS 回调地址

查询 ElevenLabs 人声隔离

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "audios": [
    { "url": "https://file.runapi.ai/isolated.mp3" }
  ]
}

InfiniteTalk

InfiniteTalk 提供基于单张图片、音频和文本提示词的口型驱动视频生成能力，并沿用 RunAPI 统一的异步任务接口。

InfiniteTalk 接口

任务 接口 模型
创建 from-audio 任务 创建 InfiniteTalk From Audio infinitetalk-from-audio
查询任务状态 查询 InfiniteTalk From Audio 状态 -

创建 InfiniteTalk From Audio

curl -X POST "https://runapi.ai/api/v1/infinitetalk/audio_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "infinitetalk-from-audio",
    "source_image_url": "https://cdn.runapi.ai/public/samples/portrait.jpg",
    "source_audio_url": "https://cdn.runapi.ai/public/samples/voice.mp3",
    "prompt": "A young woman with long dark hair talking on a podcast.",
    "output_resolution": "480p",
    "seed": 12345,
    "callback_url": "https://example.com/callback"
  }'

HTTP 202

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

POST https://runapi.ai/api/v1/infinitetalk/audio_to_video

参数 类型 必填 说明
model string 是 必须为 infinitetalk-from-audio
source_image_url string 是 源图片 URL
source_audio_url string 是 源音频 URL
prompt string 是 提示词，最长 5000 个字符
output_resolution string 否 480p 或 720p
seed integer 否 10000 到 1000000 之间的整数
callback_url string 否 HTTPS 回调地址

查询 InfiniteTalk From Audio 状态

curl "https://runapi.ai/api/v1/infinitetalk/audio_to_video/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    { "url": "https://file.runapi.ai/infinitetalk/video.mp4" }
  ]
}

Wan

Wan 是阿里巴巴的先进视频与图像生成模型家族，支持文本生成视频、图像生成视频、语音生成视频、动画、图像生成、参考引导文本生成视频及视频编辑等多种能力。

模型

模型 类型 价格
wan-2.2-a14b-text-to-video-turbo 文本生成视频 价格
wan-2.5-text-to-video 文本生成视频 价格
wan-2.6-text-to-video 文本生成视频 价格
wan-2.7-text-to-video 文本生成视频 价格
wan-2.2-a14b-image-to-video-turbo 图像生成视频 价格
wan-2.5-image-to-video 图像生成视频 价格
wan-2.6-image-to-video 图像生成视频 价格
wan-2.6-flash-image-to-video 图像生成视频 价格
wan-2.7-image-to-video 图像生成视频 价格
wan-2.6-edit-video 视频编辑 价格
wan-2.6-flash-edit-video 视频编辑 价格
wan-2.2-a14b-speech-to-video-turbo 语音生成视频 价格
wan-2.2-animate-move 动画 价格
wan-2.2-animate-replace 动画 价格
wan-2.7-image 图像生成 价格
wan-2.7-image-pro 图像生成 价格
wan-2.7-r2v R2V 文本生成视频 价格
wan-2.7-edit-video 视频编辑 价格

Wan 接口列表

任务 接口 方法
文本生成视频 文本生成视频 POST
查询文本生成视频状态 查询文本生成视频 GET
图像生成视频 图像生成视频 POST
查询图像生成视频状态 查询图像生成视频 GET
语音生成视频 语音生成视频 POST
动画生成 动画生成 POST
图像生成 图像生成 POST
视频编辑 视频编辑 POST

Wan 文本生成视频

文本生成视频：

curl -X POST "https://runapi.ai/api/v1/wan/text_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-2.6-text-to-video",
    "prompt": "樱花飘落的日本庭院延时摄影",
    "output_resolution": "720p",
    "aspect_ratio": "16:9"
  }'

import requests

response = requests.post(
    'https://runapi.ai/api/v1/wan/text_to_video',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'model': 'wan-2.6-text-to-video',
        'prompt': '樱花飘落的日本庭院延时摄影',
        'output_resolution': '720p',
        'aspect_ratio': '16:9',
    }
)
print(response.json())

响应：

{
  "id": "task_abc123"
}

POST /api/v1/wan/text_to_video

创建异步文本生成视频任务，通过状态查询接口轮询结果。

请求参数

参数 类型 必填 说明
model string 是 模型版本。可选值：wan-2.2-a14b-text-to-video-turbo、wan-2.5-text-to-video、wan-2.6-text-to-video、wan-2.7-text-to-video、wan-2.7-r2v
prompt string 是 视频内容的文本描述
callback_url string 否 异步完成通知的 Webhook URL
duration_seconds number 条件必填 时长（秒）。wan-2.5-* 必填
output_resolution string 否 输出分辨率，如 720p、1080p
aspect_ratio string 否 宽高比：16:9、9:16、1:1、4:3、3:4。不适用于 wan-2.7-*
ratio string 否 替代比例格式，仅 wan-2.7-* 支持
negative_prompt string 否 不希望出现的内容。wan-2.5-* 和 wan-2.7-* 支持
reference_image_urls array 否 wan-2.7-r2v 的参考图像 URL 列表。参考图像或参考视频至少提供一个
reference_video_urls array 否 wan-2.7-r2v 的参考视频 URL 列表。参考图像或参考视频至少提供一个
first_frame_image_url string 否 wan-2.7-r2v 的首帧图像 URL
reference_audio_url string 否 wan-2.7-r2v 的参考音频 URL
enable_prompt_expansion boolean 否 自动扩展提示词
seed integer 否 随机种子，用于结果复现
enable_safety_checker boolean 否 内容安全检查开关
watermark boolean 否 添加水印。仅 wan-2.7-* 支持
background_audio_url string 否 背景音频 URL。仅 wan-2.7-text-to-video 支持

Wan 2.7 R2V 文本生成视频

POST /api/v1/wan/text_to_video

使用 wan-2.7-r2v 模型，通过参考图像或参考视频引导文本生成视频。reference_image_urls 与 reference_video_urls 合计需要 1-5 个 URL。

{
  "model": "wan-2.7-r2v",
  "prompt": "一个人在秋天的公园里穿过落叶",
  "reference_image_urls": ["https://cdn.runapi.ai/public/samples/portrait.jpg"],
  "output_resolution": "1080p"
}

响应

完成时响应：

{
  "id": "task_abc123",
  "status": "completed",
  "videos": [
    { "url": "https://file.runapi.ai/result.mp4" }
  ]
}
字段 类型 说明
id string 任务 ID
status string processing、completed 或 failed
videos array 生成的视频对象数组，包含 url 字段（完成后）
error string 错误信息（失败时）

Wan 图像生成视频

POST /api/v1/wan/image_to_video

创建异步图像生成视频任务。

请求参数

参数 类型 必填 说明
model string 是 模型版本。可选值：wan-2.2-a14b-image-to-video-turbo、wan-2.5-image-to-video、wan-2.6-image-to-video、wan-2.6-flash-image-to-video、wan-2.7-image-to-video
prompt string 条件必填 文本提示词。wan-2.6-* 和 wan-2.7-* 必填
first_frame_image_url string 条件必填 首帧源图像 URL。wan-2.2-*、wan-2.5-* 和 wan-2.6-* 必填；wan-2.7-* 可用于首帧控制
duration_seconds number 条件必填 时长（秒）。wan-2.5-* 必填
callback_url string 否 异步完成通知的 Webhook URL
output_resolution string 否 输出分辨率
aspect_ratio string 否 宽高比。wan-2.2-* 和 wan-2.5-* 支持
negative_prompt string 否 不希望出现的内容
enable_safety_checker boolean 否 内容安全检查开关
watermark boolean 否 添加水印。仅 wan-2.7-* 支持
audio boolean 否 生成音频。仅 flash 模型支持
multi_shots boolean 否 多镜头模式。仅 flash 模型支持

Wan 语音生成视频

POST /api/v1/wan/speech_to_video

请求参数

参数 类型 必填 说明
model string 是 wan-2.2-a14b-speech-to-video-turbo
source_image_url string 是 肖像源图像 URL
source_audio_url string 是 驱动语音音频 URL
prompt string 否 补充描述提示词
callback_url string 否 异步完成通知的 Webhook URL
num_frames integer 否 输出帧数
frames_per_second integer 否 每秒帧数
output_resolution string 否 输出分辨率
negative_prompt string 否 不希望出现的内容
seed integer 否 随机种子
enable_safety_checker boolean 否 内容安全检查开关

Wan 动画生成

POST /api/v1/wan/animate

请求参数

参数 类型 必填 说明
model string 是 wan-2.2-animate-move 或 wan-2.2-animate-replace
reference_video_url string 是 动作参考视频 URL
source_image_url string 是 角色/主体图像 URL
callback_url string 否 异步完成通知的 Webhook URL
output_resolution string 否 输出分辨率
enable_safety_checker boolean 否 内容安全检查开关

Wan 图像生成

POST /api/v1/wan/text_to_image

请求参数

参数 类型 必填 说明
model string 是 wan-2.7-image 或 wan-2.7-image-pro
prompt string 是 图像内容的文本描述
callback_url string 否 异步完成通知的 Webhook URL
aspect_ratio string 否 宽高比：1:1、16:9、4:3、21:9、3:4、9:16、8:1、1:8
output_resolution string 否 输出分辨率
output_count integer 否 生成图像数量
enable_sequential boolean 否 顺序生成模式
thinking_mode boolean 否 增强推理模式。仅 wan-2.7-image-pro 支持
watermark boolean 否 添加水印
seed integer 否 随机种子
enable_safety_checker boolean 否 内容安全检查开关
source_image_urls array 否 图像编辑用源图像 URL 列表
color_palette array 否 颜色调色板约束，每项格式：{ hex, ratio }
bbox_list array 否 边界框约束

Wan 视频编辑

POST /api/v1/wan/edit_video

请求参数

参数 类型 必填 说明
model string 是 wan-2.6-edit-video、wan-2.6-flash-edit-video 或 wan-2.7-edit-video
source_video_url string wan-2.7-edit-video 必填 源视频 URL
source_video_urls array wan-2.6-edit-video 和 wan-2.6-flash-edit-video 必填 源视频 URL 列表
prompt string 否 编辑意图的文本描述
callback_url string 否 异步完成通知的 Webhook URL
negative_prompt string 否 不希望出现的内容
reference_image_url string 否 风格参考图像 URL
output_resolution string 否 输出分辨率
aspect_ratio string 否 输出宽高比
duration_seconds number 否 输出时长（秒）
audio_setting string 否 音频处理设置
audio boolean 否 生成音频，仅 Flash 模型
multi_shots boolean 否 多镜头模式，仅 Flash 模型
enable_prompt_expansion boolean 否 自动扩展提示词
watermark boolean 否 添加水印
seed integer 否 随机种子
enable_safety_checker boolean 否 内容安全检查开关

Luma

Luma 视频修改支持把一个公开可访问的视频按提示词改造成新版本。提交一次源视频后，可以轮询任务状态，或者传入 callback_url 接收异步结果。

接口列表

任务 接口 方法
创建视频修改任务 Create Luma Video Modification POST
查询任务状态 Get Luma Video Modification GET

Create Luma Video Modification

创建一个 Luma 视频修改任务：

curl -X POST "https://runapi.ai/api/v1/luma/modify_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Turn the street into a rainy cyberpunk night with neon reflections",
    "source_video_url": "https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerJoyrides.mp4",
    "callback_url": "https://your-domain.com/api/callbacks/luma",
    "watermark": "demo-watermark"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/luma/modify_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  prompt: 'Turn the street into a rainy cyberpunk night with neon reflections',
  source_video_url: 'https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerJoyrides.mp4',
  callback_url: 'https://your-domain.com/api/callbacks/luma',
  watermark: 'demo-watermark'
}.to_json

response = http.request(request)
puts response.body

import requests

response = requests.post(
    'https://runapi.ai/api/v1/luma/modify_video',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'prompt': 'Turn the street into a rainy cyberpunk night with neon reflections',
        'source_video_url': 'https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerJoyrides.mp4',
        'callback_url': 'https://your-domain.com/api/callbacks/luma',
        'watermark': 'demo-watermark'
    }
)
print(response.json())

fetch('https://runapi.ai/api/v1/luma/modify_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'Turn the street into a rainy cyberpunk night with neon reflections',
    source_video_url: 'https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerJoyrides.mp4',
    callback_url: 'https://your-domain.com/api/callbacks/luma',
    watermark: 'demo-watermark'
  })
}).then(r => r.json()).then(console.log);

HTTP 202 - 任务已接受：

{
  "id": "task_abc123",
  "status": "processing"
}

POST /api/v1/luma/modify_video

创建一个异步视频修改任务。

请求参数

参数 类型 必填 说明
prompt string 是 描述如何修改源视频的英文提示词
source_video_url string 是 公开可访问的源视频 URL，支持 MP4、MOV、AVI
callback_url string 否 用于接收完成事件的 HTTPS 回调地址
watermark string 否 要添加到结果视频中的水印标识

响应字段

字段 类型 说明
id string 任务 ID，可用于轮询或回调
status string 初始异步状态，通常为 processing

回调格式

如果传入了 callback_url，任务结束后会向该地址发送 POST 请求。

成功回调示例：

{
  "id": "task_abc123",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/generated-video.mp4"
    }
  ],
  "sources": [
    {
      "url": "https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerJoyrides.mp4"
    }
  ]
}

失败回调示例：

{
  "id": "task_abc123",
  "status": "failed",
  "error": "Modify record generation failed."
}

Get Luma Video Modification

查询任务状态与结果：

curl -X GET "https://runapi.ai/api/v1/luma/modify_video/task_abc123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

task_id = 'task_abc123'
uri = URI("https://runapi.ai/api/v1/luma/modify_video/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

import requests

task_id = 'task_abc123'
response = requests.get(
    f'https://runapi.ai/api/v1/luma/modify_video/{task_id}',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
print(response.json())

const taskId = 'task_abc123';

fetch(`https://runapi.ai/api/v1/luma/modify_video/${taskId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
}).then(r => r.json()).then(console.log);

HTTP 200 - 已完成：

{
  "id": "task_abc123",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/generated-video.mp4"
    }
  ],
  "sources": [
    {
      "url": "https://storage.googleapis.com/gtv-videos-bucket/sample/ForBiggerJoyrides.mp4"
    }
  ]
}

GET /api/v1/luma/modify_video/:id

返回任务的最新状态。Luma 提供方的 callback failed 状态会被归一化为 completed，因为视频生成本身已经成功。

响应字段

字段 类型 说明
id string 任务 ID
status string processing、completed 或 failed
videos array 任务完成后的结果视频 URL
sources array 本次修改使用的源视频 URL
error string 任务失败时的错误信息

Hailuo

RunAPI 上的 Hailuo 提供两个异步资源：文生视频与图生视频。

模型

模型 Endpoint 说明
hailuo-02-text-to-video-pro POST /api/v1/hailuo/text_to_video 固定配置的 Pro 文生视频
hailuo-02-text-to-video-standard POST /api/v1/hailuo/text_to_video Standard 文生视频，支持 duration_seconds
hailuo-02-image-to-video-pro POST /api/v1/hailuo/image_to_video 固定配置的 Pro 图生视频
hailuo-02-image-to-video-standard POST /api/v1/hailuo/image_to_video 支持 duration_seconds、output_resolution、可选 last_frame_image_url
hailuo-2.3-image-to-video-pro POST /api/v1/hailuo/image_to_video 支持 duration_seconds、output_resolution
hailuo-2.3-image-to-video-standard POST /api/v1/hailuo/image_to_video 支持 duration_seconds、output_resolution

创建文生视频

POST https://runapi.ai/api/v1/hailuo/text_to_video

参数 类型 必填 说明
model string 是 hailuo-02-text-to-video-pro 或 hailuo-02-text-to-video-standard
prompt string 是 最多 1500 字符
duration_seconds number 否 6 或 10，仅 hailuo-02-text-to-video-standard 支持，默认 6
prompt_optimizer boolean 否 是否启用 Hailuo prompt 优化
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 HTTPS 回调地址

创建图生视频

POST https://runapi.ai/api/v1/hailuo/image_to_video

参数 类型 必填 说明
model string 是 任一 Hailuo 图生视频模型
prompt string 是 hailuo-02-* 最多 1500 字符；hailuo-2.3-* 最多 5000 字符
first_frame_image_url string 是 公网可访问的首帧图 URL
last_frame_image_url string 否 末帧图片 URL，仅 hailuo-02-* 支持
duration_seconds number 否 6 或 10，Standard / 2.3 模型支持
output_resolution string 否 hailuo-02-image-to-video-standard 支持 512p / 768p；2.3 模型支持 768p / 1080p
prompt_optimizer boolean 否 仅 hailuo-02-* 支持
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 HTTPS 回调地址

查询任务状态

完成响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://tempfile.runapi.ai/hailuo/output.mp4"
    }
  ]
}

GPT Image

GPT Image 是一系列先进的图像生成模型，支持文生图和图像编辑，提供多种宽高比的高质量输出。

模型

模型 类型
gpt-image-1.5 文生图
gpt-image-1.5 图像编辑

GPT Image 端点概览

任务 端点 方法
生成图像 生成图像 POST
检查生成状态 获取生成状态 GET
编辑图像 编辑图像 POST
检查编辑状态 获取编辑状态 GET

生成图像

文生图：

curl -X POST "https://runapi.ai/api/v1/gpt_image/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1.5",
    "prompt": "一位宇航员漂浮在太空中的逼真肖像，背景是地球",
    "aspect_ratio": "1:1",
    "quality": "high"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/gpt_image/text_to_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'gpt-image-1.5',
  prompt: '一位宇航员漂浮在太空中的逼真肖像，背景是地球',
  aspect_ratio: '1:1',
  quality: 'high'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/gpt_image/text_to_image'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-image-1.5',
    'prompt': '一位宇航员漂浮在太空中的逼真肖像，背景是地球',
    'aspect_ratio': '1:1',
    'quality': 'high'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'gpt-image-1.5',
  prompt: '一位宇航员漂浮在太空中的逼真肖像，背景是地球',
  aspect_ratio: '1:1',
  quality: 'high'
};

fetch('https://runapi.ai/api/v1/gpt_image/text_to_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

使用 GPT Image 创建新的文生图任务。

HTTP 请求

POST https://runapi.ai/api/v1/gpt_image/text_to_image

请求参数

参数 类型 必需 说明
model string 是 gpt-image-1.5
prompt string 是 期望图像的文本描述
aspect_ratio string 是 输出宽高比：1:1、2:3、3:2
quality string 是 输出质量：medium、high
callback_url string 否 完成回调的 URL

响应

返回用于检查生成状态的任务 ID：

字段 类型 说明
id string 唯一任务标识符
status string 初始状态：processing

Callback 格式

如果提供了 callback_url，生成完成时将发送 POST 请求。

成功响应: - 包含 status: "completed" - 包含 images 数组，含生成的图像 URL

失败响应: - 包含 status: "failed" - 包含 error 消息，描述失败原因

成功回调示例：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/generated/image1.png"
    }
  ]
}

失败回调示例：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "error": "Generation failed"
}

获取生成状态

轮询生成结果：

curl "https://runapi.ai/api/v1/gpt_image/text_to_image/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

require 'net/http'
require 'uri'

task_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
uri = URI("https://runapi.ai/api/v1/gpt_image/text_to_image/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

import requests

task_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
url = f'https://runapi.ai/api/v1/gpt_image/text_to_image/{task_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

fetch(`https://runapi.ai/api/v1/gpt_image/text_to_image/${taskId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

处理中：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

已完成：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/generated/image1.png"
    }
  ]
}

失败：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "error": "Generation failed."
}

检索 GPT Image 文生图任务的状态和结果。

HTTP 请求

GET https://runapi.ai/api/v1/gpt_image/text_to_image/:id

URL 参数

参数 说明
id 创建请求返回的任务 ID

响应字段

字段 类型 说明
id string 唯一任务标识符
status string 任务状态：processing、completed、failed
images array 图像对象数组（仅在状态为 completed 时存在）
images[].url string 临时生成图片 URL，有效期为 7 天
error string 错误消息（仅在状态为 failed 时存在）

状态值

编辑图像

图像编辑：

curl -X POST "https://runapi.ai/api/v1/gpt_image/edit_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1.5",
    "prompt": "将这张照片转换为充满活力的暖色秋天油画风格",
    "source_image_urls": [
      "https://cdn.runapi.ai/public/samples/image.jpg"
    ],
    "aspect_ratio": "3:2",
    "quality": "high"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/gpt_image/edit_image')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'gpt-image-1.5',
  prompt: '将这张照片转换为充满活力的暖色秋天油画风格',
  source_image_urls: [
    'https://cdn.runapi.ai/public/samples/image.jpg'
  ],
  aspect_ratio: '3:2',
  quality: 'high'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/gpt_image/edit_image'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'gpt-image-1.5',
    'prompt': '将这张照片转换为充满活力的暖色秋天油画风格',
    'source_image_urls': [
        'https://cdn.runapi.ai/public/samples/image.jpg'
    ],
    'aspect_ratio': '3:2',
    'quality': 'high'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'gpt-image-1.5',
  prompt: '将这张照片转换为充满活力的暖色秋天油画风格',
  source_image_urls: [
    'https://cdn.runapi.ai/public/samples/image.jpg'
  ],
  aspect_ratio: '3:2',
  quality: 'high'
};

fetch('https://runapi.ai/api/v1/gpt_image/edit_image', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
  "status": "processing"
}

使用 GPT Image 创建新的图像编辑任务。

HTTP 请求

POST https://runapi.ai/api/v1/gpt_image/edit_image

请求参数

参数 类型 必需 说明
model string 是 gpt-image-1.5
prompt string 是 期望编辑效果的文本描述
source_image_urls array 是 源图像 URL 数组（最多 16 张图片）
aspect_ratio string 是 输出宽高比：1:1、2:3、3:2
quality string 是 输出质量：medium、high
callback_url string 否 完成回调的 URL

响应

返回用于检查编辑状态的任务 ID：

字段 类型 说明
id string 唯一任务标识符
status string 初始状态：processing

Callback 格式

如果提供了 callback_url，编辑完成时将发送 POST 请求。

成功回调示例：

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/edited/image1.png"
    }
  ]
}

失败回调示例：

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
  "status": "failed",
  "error": "Edit failed"
}

获取编辑状态

轮询编辑结果：

curl "https://runapi.ai/api/v1/gpt_image/edit_image/b2c3d4e5-f6a7-8901-bcde-f01234567891" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

require 'net/http'
require 'uri'

task_id = 'b2c3d4e5-f6a7-8901-bcde-f01234567891'
uri = URI("https://runapi.ai/api/v1/gpt_image/edit_image/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

import requests

task_id = 'b2c3d4e5-f6a7-8901-bcde-f01234567891'
url = f'https://runapi.ai/api/v1/gpt_image/edit_image/{task_id}'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(url, headers=headers)
print(response.json())

const taskId = 'b2c3d4e5-f6a7-8901-bcde-f01234567891';

fetch(`https://runapi.ai/api/v1/gpt_image/edit_image/${taskId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

处理中：

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
  "status": "processing"
}

已完成：

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/edited/image1.png"
    }
  ]
}

失败：

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
  "status": "failed",
  "error": "Edit failed."
}

检索 GPT Image 图像编辑任务的状态和结果。

HTTP 请求

GET https://runapi.ai/api/v1/gpt_image/edit_image/:id

URL 参数

参数 说明
id 创建请求返回的任务 ID

响应字段

字段 类型 说明
id string 唯一任务标识符
status string 任务状态：processing、completed、failed
images array 图像对象数组（仅在状态为 completed 时存在）
images[].url string 临时编辑图片 URL，有效期为 7 天
error string 错误消息（仅在状态为 failed 时存在）

状态值

GPT Image 2

GPT Image 2 支持文生图和图片编辑。

模型

模型 类型
gpt-image-2 文生图
gpt-image-2 图片编辑

端点

任务 端点 方法
生成图像 生成图像 POST
检查生成状态 获取生成状态 GET
编辑图像 编辑图像 POST
检查编辑状态 获取编辑状态 GET

GPT Image 2 生成图像

文生图：

curl -X POST "https://runapi.ai/api/v1/gpt_image_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic night city poster with neon reflections on a rainy street",
    "aspect_ratio": "16:9",
    "output_resolution": "2k"
  }'

POST https://runapi.ai/api/v1/gpt_image_2/text_to_image

请求参数

参数 类型 必填 说明
model string 是 gpt-image-2
prompt string 是 文本提示词，最多 20,000 个字符
aspect_ratio string 否 auto、1:1、9:16、16:9、4:3、3:4
output_resolution string 否 1k、2k、4k。1:1 不能转 4k；auto/不传时只支持 1k
callback_url string 否 完成回调地址

响应

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

GPT Image 2 获取生成状态

GET https://runapi.ai/api/v1/gpt_image_2/text_to_image/:id

返回当前任务状态，任务完成后会包含 images。

GPT Image 2 编辑图像

图片编辑：

curl -X POST "https://runapi.ai/api/v1/gpt_image_2/edit_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Transform this product image into a premium e-commerce poster style",
    "source_image_urls": ["https://raw.githubusercontent.com/github/explore/main/topics/python/python.png"],
    "aspect_ratio": "16:9",
    "output_resolution": "2k"
  }'

POST https://runapi.ai/api/v1/gpt_image_2/edit_image

请求参数

参数 类型 必填 说明
model string 是 gpt-image-2
prompt string 是 文本提示词，最多 20,000 个字符
source_image_urls array 是 源图片 URL 数组，最多 16 张
aspect_ratio string 否 auto、1:1、9:16、16:9、4:3、3:4
output_resolution string 否 1k、2k、4k。1:1 不能转 4k；auto/不传时只支持 1k
callback_url string 否 完成回调地址

响应

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
  "status": "processing"
}

GPT Image 2 获取编辑状态

GET https://runapi.ai/api/v1/gpt_image_2/edit_image/:id

返回当前任务状态，任务完成后会包含 images。

GPT-4o Image

GPT-4o Image 支持文生图、图像引导和变体输出任务。

模型

模型 类型
gpt-4o-image 文生图 / 编辑 / 变体

端点

任务 端点 方法
创建文生图任务 创建文生图 POST
检查任务状态 获取任务状态 GET

GPT-4o Image 创建文生图

文本、图像引导或变体请求：

curl -X POST "https://runapi.ai/api/v1/gpt_4o_image/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-image",
    "prompt": "A premium watch product photo on black stone",
    "aspect_ratio": "1:1",
    "source_image_urls": ["https://raw.githubusercontent.com/github/explore/main/topics/python/python.png"],
    "output_count": 2
  }'

POST https://runapi.ai/api/v1/gpt_4o_image/text_to_image

请求参数

参数 类型 必填 说明
model string 是 gpt-4o-image
prompt string 条件必填 当 source_image_urls 为空时必填
aspect_ratio string 是 1:1、3:2、2:3
source_image_urls array 否 最多 5 个源图 URL
mask_url string 否 局部编辑遮罩图 URL
output_count integer 否 生成图片数量：1、2 或 4
enable_prompt_expansion boolean 否 提示词扩写开关
callback_url string 否 完成回调地址

响应

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}

GPT-4o Image 获取任务状态

GET https://runapi.ai/api/v1/gpt_4o_image/text_to_image/:id

返回当前任务状态，任务完成后会包含 progress 和 images。

Grok-Imagine

Grok-Imagine 是 RunAPI 上的多模态生成模型系列。支持文生视频、图生视频、文生图、图像编辑，以及在已有视频任务上进行扩展（extend）和超分（upscale）。

模型版本

模型 说明 适用场景
grok-imagine-text-to-video 文本驱动的视频生成，支持运动风格控制 创意构思与风格化短片
grok-imagine-image-to-video 由一张或多张参考图生成视频 将静态画面动起来
grok-imagine-text-to-image 文本驱动的图像生成，可选 Pro 高质量模式 主视觉与概念图
grok-imagine-edit-image 编辑单张来源图像 风格再创作

Grok-Imagine 端点概览

任务 端点 模型
创建文生视频任务 创建文生视频 grok-imagine-text-to-video
创建图生视频任务 创建图生视频 grok-imagine-image-to-video
创建文生图任务 创建文生图 grok-imagine-text-to-image
创建图像编辑任务 创建编辑图片 grok-imagine-edit-image
扩展已有视频 扩展视频 -
视频超分 视频超分 -
查询任务状态 查询任务状态 -

任务生命周期

六个创建端点都是异步的。POST 成功会返回 HTTP 202 与 { "id", "status": "processing" }。通过轮询对应的 GET /:id 端点，或提供 callback_url，即可获取最终结果。

创建 Grok-Imagine 文生视频

创建一个文生视频任务：

curl -X POST "https://runapi.ai/api/v1/grok_imagine/text_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-text-to-video",
    "prompt": "A neon dragon gliding over a rain-soaked Tokyo street at night",
    "aspect_ratio": "16:9",
    "motion_style": "normal",
    "duration_seconds": 10,
    "output_resolution": "720p",
    "enable_safety_checker": false,
    "callback_url": "https://your-domain.com/api/callback"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://runapi.ai/api/v1/grok_imagine/text_to_video')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request['Content-Type'] = 'application/json'
request.body = {
  model: 'grok-imagine-text-to-video',
  prompt: 'A neon dragon gliding over a rain-soaked Tokyo street at night',
  aspect_ratio: '16:9',
  motion_style: 'normal',
  duration_seconds: 10,
  output_resolution: '720p',
  enable_safety_checker: false,
  callback_url: 'https://your-domain.com/api/callback'
}.to_json

response = http.request(request)
puts response.body

import requests

url = 'https://runapi.ai/api/v1/grok_imagine/text_to_video'
headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}
data = {
    'model': 'grok-imagine-text-to-video',
    'prompt': 'A neon dragon gliding over a rain-soaked Tokyo street at night',
    'aspect_ratio': '16:9',
    'motion_style': 'normal',
    'duration_seconds': 10,
    'output_resolution': '720p',
    'enable_safety_checker': False,
    'callback_url': 'https://your-domain.com/api/callback'
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const data = {
  model: 'grok-imagine-text-to-video',
  prompt: 'A neon dragon gliding over a rain-soaked Tokyo street at night',
  aspect_ratio: '16:9',
  motion_style: 'normal',
  duration_seconds: 10,
  output_resolution: '720p',
  enable_safety_checker: false,
  callback_url: 'https://your-domain.com/api/callback'
};

fetch('https://runapi.ai/api/v1/grok_imagine/text_to_video', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

HTTP 202 - 任务已接受：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/grok_imagine/text_to_video

请求参数

参数 类型 必需 说明
model string 是 必须为 grok-imagine-text-to-video
prompt string 是 最长 5000 字符
aspect_ratio string 否 2:3、3:2、1:1、16:9、9:16，默认 2:3
motion_style string 否 fun、normal、spicy，默认 normal
duration_seconds integer 否 视频时长（秒），范围 6 到 30
output_resolution string 否 480p 或 720p，默认 480p
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 HTTPS 回调地址

创建 Grok-Imagine 图生视频

使用参考图创建图生视频任务：

curl -X POST "https://runapi.ai/api/v1/grok_imagine/image_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-to-video",
    "source_image_urls": [
      "https://cdn.runapi.ai/public/samples/image-to-video.jpg"
    ],
    "prompt": "Slow dolly-in on the subject as wind ruffles the hair",
    "motion_style": "normal",
    "duration_seconds": 8,
    "output_resolution": "720p",
    "aspect_ratio": "16:9",
    "enable_safety_checker": false,
    "callback_url": "https://your-domain.com/api/callback"
  }'

或者直接基于之前某次 grok-imagine-text-to-image 任务生成的图片：

curl -X POST "https://runapi.ai/api/v1/grok_imagine/image_to_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-to-video",
    "source_task_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "index": 0,
    "prompt": "Gentle camera orbit around the subject",
    "duration_seconds": 10,
    "output_resolution": "720p"
  }'

HTTP 202 - 任务已接受：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/grok_imagine/image_to_video

请求参数

参数 类型 必需 说明
model string 是 必须为 grok-imagine-image-to-video
source_image_urls array 条件必需 仅支持 1 条来源图 URL，与 source_task_id 二选一
source_task_id string 条件必需 之前 grok-imagine-text-to-image 任务返回的任务 ID，与 source_image_urls 二选一
index integer 否 使用 source_task_id 时指定动画化第几张图（0-5）
prompt string 否 运动提示词
motion_style string 否 fun、normal、spicy。使用 source_image_urls 时不支持 spicy
duration_seconds integer 否 视频时长（秒），范围 6 到 30
output_resolution string 否 480p 或 720p
aspect_ratio string 否 2:3、3:2、1:1、16:9、9:16，默认 16:9
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 HTTPS 回调地址

创建 Grok-Imagine 文生图

创建一个文生图任务：

curl -X POST "https://runapi.ai/api/v1/grok_imagine/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-text-to-image",
    "prompt": "A cyberpunk fox warrior standing on a rooftop overlooking a neon city",
    "aspect_ratio": "1:1",
    "enable_pro": true,
    "enable_safety_checker": false,
    "callback_url": "https://your-domain.com/api/callback"
  }'

HTTP 202 - 任务已接受：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/grok_imagine/text_to_image

请求参数

参数 类型 必需 说明
model string 是 必须为 grok-imagine-text-to-image
prompt string 是 最长 5000 字符
aspect_ratio string 否 2:3、3:2、1:1、16:9、9:16，默认 1:1
enable_pro boolean 否 是否启用 Pro 高质量模式，默认 false
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 HTTPS 回调地址

创建 Grok-Imagine 编辑图片

创建一个图像编辑任务：

curl -X POST "https://runapi.ai/api/v1/grok_imagine/edit_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-edit-image",
    "source_image_url": "https://cdn.runapi.ai/public/samples/image.jpg",
    "prompt": "Reimagine the subject as an oil painting",
    "enable_safety_checker": false,
    "callback_url": "https://your-domain.com/api/callback"
  }'

HTTP 202 - 任务已接受：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/grok_imagine/edit_image

请求参数

参数 类型 必需 说明
model string 是 必须为 grok-imagine-edit-image
source_image_url string 是 来源图像 URL
prompt string 否 图像编辑提示词
enable_safety_checker boolean 否 内容安全检查开关
callback_url string 否 HTTPS 回调地址

扩展 Grok-Imagine 视频

在已生成的 Grok-Imagine 视频基础上追加片段：

curl -X POST "https://runapi.ai/api/v1/grok_imagine/extend_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_task_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "prompt": "Continue with the dragon soaring above the skyline",
    "start_seconds": 6,
    "extension_duration_seconds": 6,
    "callback_url": "https://your-domain.com/api/callback"
  }'

HTTP 202 - 任务已接受：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/grok_imagine/extend_video

请求参数

参数 类型 必需 说明
source_task_id string 是 同一账号下之前某次 Grok-Imagine 视频任务的任务 ID（grok-imagine-text-to-video 或 grok-imagine-image-to-video）
prompt string 是 扩展段落的提示词
start_seconds integer 是 源视频中开始扩展的秒数
extension_duration_seconds integer 是 6 或 10 — 追加片段的时长（秒）
callback_url string 否 HTTPS 回调地址

超分 Grok-Imagine 视频

对已生成的 Grok-Imagine 视频做超分：

curl -X POST "https://runapi.ai/api/v1/grok_imagine/upscale_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_task_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "callback_url": "https://your-domain.com/api/callback"
  }'

HTTP 202 - 任务已接受：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

HTTP 请求

POST https://runapi.ai/api/v1/grok_imagine/upscale_image

请求参数

参数 类型 必需 说明
source_task_id string 是 同一账号下之前某次 Grok-Imagine 视频任务的任务 ID。超分仅支持 480p 来源视频。
callback_url string 否 HTTPS 回调地址

查询 Grok-Imagine 任务状态

每个创建端点都有一个对应的状态查询端点，路径相同再加 /:id。轮询该端点即可获取任务进度或最终结果。

创建端点 状态端点
POST /api/v1/grok_imagine/text_to_video GET /api/v1/grok_imagine/text_to_video/:id
POST /api/v1/grok_imagine/image_to_video GET /api/v1/grok_imagine/image_to_video/:id
POST /api/v1/grok_imagine/text_to_image GET /api/v1/grok_imagine/text_to_image/:id
POST /api/v1/grok_imagine/edit_image GET /api/v1/grok_imagine/edit_image/:id
POST /api/v1/grok_imagine/extend_video GET /api/v1/grok_imagine/extend_video/:id
POST /api/v1/grok_imagine/upscale_image GET /api/v1/grok_imagine/upscale_image/:id

查询 Grok-Imagine 任务：

curl "https://runapi.ai/api/v1/grok_imagine/text_to_video/YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

task_id = 'YOUR_TASK_ID'
uri = URI("https://runapi.ai/api/v1/grok_imagine/text_to_video/#{task_id}")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

task_id = 'YOUR_TASK_ID'
response = requests.get(
    f'https://runapi.ai/api/v1/grok_imagine/text_to_video/{task_id}',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
print(response.json())

const taskId = 'YOUR_TASK_ID';

fetch(`https://runapi.ai/api/v1/grok_imagine/text_to_video/${taskId}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
})
.then(res => res.json())
.then(data => console.log(data));

视频完成响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "videos": [
    {
      "url": "https://file.runapi.ai/grok-imagine/generated-video.mp4"
    }
  ]
}

图像完成响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "images": [
    {
      "url": "https://file.runapi.ai/grok-imagine/generated-image.png"
    }
  ]
}

失败响应示例：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Generation failed"
}

响应字段

字段 类型 说明
id string 任务标识符
status string processing、completed 或 failed
videos array 视频任务完成时返回的视频 URL
images array 图像任务完成时返回的图片 URL
error string 任务失败时的错误信息

Callback 格式

如果创建任务时提供了 callback_url，任务完成时会向该地址发起 POST 回调，请求体与上文的完成 / 失败响应一致。

Topaz

Topaz 在 RunAPI 上提供图像放大与视频放大两个独立接口。

模型

模型 类型 价格
topaz-upscale-image 图像放大 价格
topaz-upscale-video 视频放大 价格

端点

任务 端点 方法
图像放大 图像放大 POST
查询图像放大状态 获取图像放大状态 GET
视频放大 视频放大 POST
查询视频放大状态 获取视频放大状态 GET

Topaz 图像放大

curl -X POST "https://runapi.ai/api/v1/topaz/upscale_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topaz-upscale-image",
    "source_image_url": "https://cdn.runapi.ai/public/samples/upscale.jpg",
    "upscale_factor": 4
  }'

POST https://runapi.ai/api/v1/topaz/upscale_image

请求参数

参数 类型 必填 说明
model string 是 topaz-upscale-image
source_image_url string 是 可公开访问的输入图片 URL
upscale_factor number 是 1、2、4 或 8
callback_url string 否 完成回调地址

响应

{
  "id": "img-task-123",
  "status": "processing"
}

Topaz 获取图像放大状态

GET https://runapi.ai/api/v1/topaz/upscale_image/:id

返回当前任务状态，任务完成后会包含 images。

Topaz 视频放大

curl -X POST "https://runapi.ai/api/v1/topaz/upscale_video" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topaz-upscale-video",
    "source_video_url": "https://cdn.runapi.ai/public/samples/video-lowres.mp4",
    "upscale_factor": 2
  }'

POST https://runapi.ai/api/v1/topaz/upscale_video

请求参数

参数 类型 必填 说明
model string 是 topaz-upscale-video
source_video_url string 是 可公开访问的输入视频 URL
upscale_factor number 否 1、2 或 4；省略时使用服务默认值
callback_url string 否 完成回调地址

响应

{
  "id": "vid-task-123",
  "status": "processing"
}

Topaz 获取视频放大状态

GET https://runapi.ai/api/v1/topaz/upscale_video/:id

返回当前任务状态，任务完成后会包含 videos。

GPT LLM

通过 RunAPI 访问 OpenAI GPT 与文本向量模型。API 支持 Chat Completions、Responses API 和 OpenAI 兼容 Embeddings。

SDK 快速开始

使用 OpenAI Python SDK：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_TOKEN",
    base_url="https://runapi.ai/v1"
)

# Chat Completions (GPT 5.2)
response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[
        {"role": "user", "content": "你好！"}
    ]
)
print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_TOKEN',
  baseURL: 'https://runapi.ai/v1',
});

// Chat Completions (GPT 5.2)
const response = await client.chat.completions.create({
  model: 'gpt-5.2',
  messages: [
    { role: 'user', content: '你好！' }
  ],
});
console.log(response.choices[0].message.content);

require "openai"

client = OpenAI::Client.new(
  access_token: "YOUR_API_TOKEN",
  uri_base: "https://runapi.ai/v1"
)

response = client.chat(
  parameters: {
    model: "gpt-5.2",
    messages: [
      { role: "user", content: "你好！" }
    ]
  }
)
puts response.dig("choices", 0, "message", "content")

curl -X POST "https://runapi.ai/v1/chat/completions" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "messages": [
      {"role": "user", "content": "你好！"}
    ]
  }'

将 base_url 设置为 https://runapi.ai/v1，使用你的 RunAPI API Key。

模型

模型 版本字符串 端点 功能
GPT 5.5 gpt-5.5 /v1/responses 对话、多模态输入、网页搜索、函数调用、推理
GPT 5.2 gpt-5.2 /v1/chat/completions 对话、网页搜索、推理控制
GPT 5.4 gpt-5.4 /v1/responses 对话、多模态输入、网页搜索、函数调用、推理
GPT Codex gpt-5-codex /v1/responses 代码生成、多模态、网页搜索、函数调用、推理
GPT Codex gpt-5.1-codex /v1/responses 代码生成、多模态、网页搜索、函数调用、推理
GPT Codex gpt-5.2-codex /v1/responses 代码生成、多模态、网页搜索、函数调用、推理
GPT Codex gpt-5.3-codex /v1/responses 代码生成、多模态、网页搜索、函数调用、推理
GPT Codex gpt-5.4-codex /v1/responses 代码生成、多模态、网页搜索、函数调用、推理
Text Embedding 3 Large text-embedding-3-large /v1/embeddings 高容量文本向量
Text Embedding 3 Small text-embedding-3-small /v1/embeddings 高效文本向量
Text Embedding Ada 002 text-embedding-ada-002 /v1/embeddings 兼容旧版文本向量

列出模型

以 OpenAI 兼容格式列出平台 LLM 模型：

curl -X GET "https://runapi.ai/v1/models" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_TOKEN", base_url="https://runapi.ai/v1")
models = client.models.list()
for model in models.data:
    print(model.id)

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.5",
      "object": "model",
      "created": 1714900000,
      "owned_by": "system"
    }
  ]
}

GET /v1/models

返回所有可用的平台 LLM 模型，格式兼容 OpenAI List Models API。如果 API Key 设置了 allowed_models 限制，则仅返回允许的模型。

Chat Completions

端点： POST https://runapi.ai/v1/chat/completions

适用于 GPT 5.2，兼容 OpenAI Chat Completions API 格式。

Chat Completions 请求：

curl -X POST "https://runapi.ai/v1/chat/completions" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "messages": [
      {"role": "user", "content": "用一句话解释量子计算。"}
    ],
    "reasoning_effort": "high"
  }'

response = client.chat.completions.create(
    model="gpt-5.2",
    messages=[
        {"role": "user", "content": "用一句话解释量子计算。"}
    ]
)

const response = await client.chat.completions.create({
  model: 'gpt-5.2',
  messages: [
    { role: 'user', content: '用一句话解释量子计算。' }
  ],
});

response = client.chat(
  parameters: {
    model: "gpt-5.2",
    messages: [
      { role: "user", content: "用一句话解释量子计算。" }
    ]
  }
)

响应：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-5.2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "量子计算利用量子比特..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 50,
    "total_tokens": 65
  }
}

参数

参数 类型 必填 说明
model string 是 模型 ID：gpt-5.2
messages array 是 包含 role 和 content 的对话消息
tools array 否 工具定义，支持 web_search
reasoning_effort string 否 "low" 或 "high"（默认："high"）
stream boolean 否 启用 SSE 流式传输（默认：false）

消息格式

消息支持文本和图像的多模态内容：

{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "这张图片里有什么？"},
        {"type": "image_url", "image_url": {"url": "https://cdn.runapi.ai/public/samples/image.jpg"}}
      ]
    }
  ]
}

Responses

端点： POST https://runapi.ai/v1/responses

适用于 GPT 5.4 和 GPT Codex 模型。使用 OpenAI Responses API 格式，支持多模态输入、推理和工具调用。

Responses API 请求：

curl -X POST "https://runapi.ai/v1/responses" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "解释相对论。",
    "reasoning": {"effort": "medium"}
  }'

import httpx

response = httpx.post(
    "https://runapi.ai/v1/responses",
    headers={"x-api-key": "YOUR_API_TOKEN"},
    json={
        "model": "gpt-5.4",
        "input": "解释相对论。",
        "reasoning": {"effort": "medium"}
    }
)
print(response.json())

const response = await fetch('https://runapi.ai/v1/responses', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-5.4',
    input: '解释相对论。',
    reasoning: { effort: 'medium' },
  }),
});
const data = await response.json();

require "net/http"
require "json"

uri = URI("https://runapi.ai/v1/responses")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["x-api-key"] = "YOUR_API_TOKEN"
request["Content-Type"] = "application/json"
request.body = {
  model: "gpt-5.4",
  input: "解释相对论。",
  reasoning: { effort: "medium" }
}.to_json

response = http.request(request)
puts JSON.parse(response.body)

响应：

{
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "相对论..."}
      ],
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 200,
    "total_tokens": 212
  },
  "status": "completed"
}

参数

参数 类型 必填 说明
model string 是 模型 ID：gpt-5.5、gpt-5.4、gpt-5-codex、gpt-5.1-codex、gpt-5.2-codex、gpt-5.3-codex、gpt-5.4-codex
input string 或 array 是 文本字符串或输入项数组
stream boolean 否 启用 SSE 流式传输（默认：false）
reasoning object 否 `{"effort": "minimal"\
tools array 否 网页搜索或函数调用工具（二选一）
tool_choice string 否 使用函数工具时设为 "auto"

输入格式

input 字段接受简单字符串或带有多模态内容的消息对象数组：

{
  "input": [
    {"role": "user", "content": [
      {"type": "input_text", "text": "描述这张图片"},
      {"type": "input_image", "image_url": "https://cdn.runapi.ai/public/samples/image.jpg"}
    ]}
  ]
}

支持的内容类型：input_text、input_image、input_file。

网页搜索工具

{
  "tools": [{"type": "web_search"}]
}

函数调用

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取当前天气",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string"}
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Embedding

端点： POST https://runapi.ai/v1/embeddings

使用 OpenAI Embeddings API 格式从文本生成向量。

Embeddings 请求：

curl -X POST "https://runapi.ai/v1/embeddings" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": ["搜索文档", "查询文本"],
    "encoding_format": "float"
  }'

response = client.embeddings.create(
    model="text-embedding-3-small",
    input=["搜索文档", "查询文本"],
    encoding_format="float"
)
print(response.data[0].embedding)

const response = await client.embeddings.create({
  model: 'text-embedding-3-small',
  input: ['搜索文档', '查询文本'],
  encoding_format: 'float',
});
console.log(response.data[0].embedding);

响应：

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.101, 0.202, 0.303]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

参数

参数 类型 必填 说明
model string 是 模型 ID：text-embedding-3-large、text-embedding-3-small 或 text-embedding-ada-002
input string 或 array 是 要生成向量的文本字符串、字符串数组或 token 数组
encoding_format string 否 "float" 或 "base64"
dimensions integer 否 缩短 text-embedding-3-large 和 text-embedding-3-small 的输出向量
user string 否 随请求转发的终端用户标识

流式传输

流式请求（Chat Completions）：

curl -X POST "https://runapi.ai/v1/chat/completions" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "stream": true,
    "messages": [
      {"role": "user", "content": "写一首关于编程的俳句。"}
    ]
  }'

流式请求（Responses API）：

curl -X POST "https://runapi.ai/v1/responses" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "stream": true,
    "input": "写一首关于编程的俳句。"
  }'

设置 "stream": true 接收服务器推送事件（SSE）。响应以 Content-Type: text/event-stream 增量流式传输。

Responses API 流式事件

事件 说明
response.output_text.delta 增量文本内容
response.function_call_arguments.delta 增量函数调用参数
response.completed 包含使用量数据的最终事件

认证

方式 请求头 示例
API Key x-api-key x-api-key: YOUR_API_TOKEN
Bearer Authorization Authorization: Bearer YOUR_API_TOKEN

计费

基于 Token 计费：积分根据实际的输入和输出 Token 使用量计算。请求前会预留一定额度，完成后根据实际使用量调整。

Gemini LLM

通过 RunAPI 以 OpenAI Chat Completions 格式访问 Google Gemini 语言模型。

SDK 快速开始

使用 OpenAI Python SDK：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_TOKEN",
    base_url="https://runapi.ai/v1"
)

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[
        {"role": "user", "content": "你好！"}
    ]
)
print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_TOKEN',
  baseURL: 'https://runapi.ai/v1',
});

const response = await client.chat.completions.create({
  model: 'gemini-2.5-flash',
  messages: [
    { role: 'user', content: '你好！' }
  ],
});
console.log(response.choices[0].message.content);

require "openai"

client = OpenAI::Client.new(
  access_token: "YOUR_API_TOKEN",
  uri_base: "https://runapi.ai/v1"
)

response = client.chat(
  parameters: {
    model: "gemini-2.5-flash",
    messages: [
      { role: "user", content: "你好！" }
    ]
  }
)
puts response.dig("choices", 0, "message", "content")

curl -X POST "https://runapi.ai/v1/chat/completions" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "你好！"}
    ]
  }'

为了尽量贴近官方 OpenAI 兼容接入方式，建议将 base_url 设置为 https://runapi.ai/v1，并使用你的 RunAPI API Key。

模型

模型 版本字符串 端点 功能
Gemini 2.5 Flash gemini-2.5-flash /v1/chat/completions 对话、多模态输入、Google Search、结构化输出、thoughts
Gemini 2.5 Pro gemini-2.5-pro /v1/chat/completions 对话、多模态输入、Google Search、结构化输出、thoughts、推理强度
Gemini 3.1 Pro gemini-3.1-pro-preview /v1/chat/completions 对话、多模态输入、Google Search、thoughts、推理强度
Gemini 3.5 Flash gemini-3.5-flash /v1beta/models/gemini-3.5-flash:generateContent 或 /v1beta/models/gemini-3.5-flash:streamGenerateContent contents 请求、多模态输入、函数调用、thoughts
Gemini 3 Flash gemini-3-flash-preview /v1/chat/completions、/v1beta/models/gemini-3-flash-preview:generateContent 或 /v1beta/models/gemini-3-flash-preview:streamGenerateContent 对话、多模态、函数调用、结构化输出、thoughts、推理强度；同时支持 contents 端点
Gemini 3 Pro gemini-3-pro-preview /v1/chat/completions 对话、多模态输入、Google Search、结构化输出、thoughts、推理强度

列出模型

以 Gemini 格式列出模型：

curl -X GET "https://runapi.ai/v1beta/models" \
  -H "x-api-key: YOUR_API_TOKEN"

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_TOKEN", base_url="https://runapi.ai/v1")
models = client.models.list()
for model in models.data:
    print(model.id)

{
  "models": [
    {
      "name": "models/gemini-3.5-flash",
      "version": "001",
      "displayName": "Gemini 3.5 Flash",
      "description": "Gemini 3.5 Flash language model",
      "inputTokenLimit": 1048576,
      "outputTokenLimit": 65536,
      "supportedGenerationMethods": ["generateContent", "streamGenerateContent"]
    }
  ]
}

GET /v1beta/models

返回所有可用的平台 LLM 模型，格式兼容 Google AI models.list API。如果 API Key 设置了 allowed_models 限制，则仅返回允许的模型。

通过 OpenAI SDK 使用 base_url="https://runapi.ai/v1" 时，调用 client.models.list() 会请求 /v1/models，以 OpenAI List Models 格式返回同一个模型目录。

Chat Completions

端点： POST https://runapi.ai/v1/chat/completions

兼容 OpenAI Chat Completions 请求格式。

Gemini 请求：

curl -X POST "https://runapi.ai/v1/chat/completions" \
  -H "x-api-key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [
      {"role": "user", "content": "总结一下最近的 AI 新闻。"}
    ],
    "include_thoughts": true,
    "reasoning_effort": "high"
  }'

结构化输出：

{
  "model": "gemini-3-pro-preview",
  "messages": [
    {"role": "user", "content": "提取标题和情绪。"}
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "article_summary",
      "schema": {
        "type": "object",
        "properties": {
          "title": {"type": "string"},
          "sentiment": {"type": "string"}
        },
        "required": ["title", "sentiment"]
      }
    }
  }
}

Gemini Contents

端点： POST https://runapi.ai/v1beta/models/{model}:generateContent 和 POST https://runapi.ai/v1beta/models/{model}:streamGenerateContent

GET /v1beta/models 返回的每个模型都可以通过这些 Gemini 兼容端点调用。模型会从 URL 路径中推断。generateContent 返回 JSON，streamGenerateContent 返回 Gemini 兼容 SSE chunks。

{
  "stream": true,
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "北京今天天气怎么样？" }
      ]
    }
  ],
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather_forecast",
          "description": "Get the weather forecast for a given location",
          "parameters": {
            "type": "OBJECT",
            "properties": {
              "location": { "type": "STRING" }
            },
            "required": ["location"]
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "includeThoughts": true,
      "thinkingLevel": "high"
    }
  }
}

参数

参数 类型 必填 说明
model string 是 模型 ID：gemini-2.5-flash、gemini-2.5-pro、gemini-3.1-pro-preview、gemini-3-flash-preview、gemini-3-pro-preview
messages array 是 包含 role 和 content 的对话消息
tools array 否 工具定义。Google Search 使用 googleSearch；自定义函数遵循 OpenAI 风格的 tool 对象
stream boolean 否 启用 SSE 流式输出
include_thoughts boolean 否 是否在响应中包含 Gemini thoughts
reasoning_effort string 否 low 或 high；这里的 Gemini 模型中除 gemini-2.5-flash 外都支持
response_format object 否 结构化输出 schema，response_format.type 必须为 json_schema

说明

额外示例

{
  "model": "gemini-3.1-pro-preview",
  "messages": [
    {"role": "user", "content": "总结一下最新的市场新闻。"}
  ],
  "include_thoughts": true,
  "reasoning_effort": "high",
  "tools": [
    {"type": "function", "function": {"name": "googleSearch"}}
  ]
}

{
  "model": "gemini-3-flash-preview",
  "messages": [
    {"role": "user", "content": "如有需要请调用工具。"}
  ],
  "reasoning_effort": "low",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "extract_entities",
        "parameters": {
          "type": "object"
        }
      }
    }
  ]
}

DeepSeek

DeepSeek 推理优先的大语言模型可通过 RunAPI 在两种表面调用：OpenAI 兼容的 Chat Completions API 与 Anthropic 兼容的 Messages API。将任一 SDK 指向 RunAPI 并传入 DeepSeek 模型 id 即可。

模型： deepseek-v4-flash（快速、低成本；可选思考模式）与 deepseek-v4-pro（前沿推理与智能体任务）。

SDK 快速上手

OpenAI SDK —— Chat Completions（https://runapi.ai/v1）：

curl https://runapi.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "你好！"}]
  }'

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_TOKEN", base_url="https://runapi.ai/v1")
resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "你好！"}],
)
print(resp.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({ apiKey: 'YOUR_API_TOKEN', baseURL: 'https://runapi.ai/v1' });
const resp = await client.chat.completions.create({
  model: 'deepseek-v4-flash',
  messages: [{ role: 'user', content: '你好！' }],
});
console.log(resp.choices[0].message.content);

Anthropic SDK —— Messages（https://runapi.ai）：

import anthropic

client = anthropic.Anthropic(api_key="YOUR_API_TOKEN", base_url="https://runapi.ai")
msg = client.messages.create(
    model="deepseek-v4-flash",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好！"}],
)
print(msg.content[0].text)

模型

模型 说明
deepseek-v4-flash 快速、低成本档位。思考（推理）模式为可选请求参数。
deepseek-v4-pro 面向最复杂与智能体任务的前沿推理。

两个模型都会出现在 GET /v1/models 的 Anthropic 与 OpenAI SDK 列表格式中。

计费

按 token 计费：积分根据实际输入/输出 token 用量计算。命中缓存的 prompt token 按更低的缓存读取价计费。

File Upload

使用 File Upload API 创建可传给媒体 URL 参数的临时文件 URL。上传文件和返回的 URL 有效期为 1 小时。

创建文件

HTTP 请求

POST https://runapi.ai/api/v1/files

请求来源

每次请求选择一种来源：

来源 Content Type 请求体
本地文件 multipart/form-data file，可选 file_name
远程 URL application/json source.type=url、source.url，可选 file_name
Base64 application/json source.type=base64、source.data，可选 file_name

本地文件示例

curl -X POST "https://runapi.ai/api/v1/files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@./image.png"

import { RunApi } from '@runapi.ai/sdk';
import { readFile } from 'node:fs/promises';

const client = new RunApi({ apiKey: process.env.RUNAPI_API_KEY });
const file = new Blob([await readFile('./image.png')], { type: 'image/png' });

const upload = await client.files.create({
  file,
  file_name: 'image.png'
});

require "runapi/files"

client = RunApi::Files.new(api_key: ENV["RUNAPI_API_KEY"])
upload = client.create(
  file: "./image.png",
  file_name: "image.png"
)

client, err := runapi.NewClient(option.WithAPIKey(os.Getenv("RUNAPI_API_KEY")))
upload, err := client.Files.Create(ctx, files.CreateParams{
  File: "image.png",
  FileName: "image.png",
})

URL 示例

curl -X POST "https://runapi.ai/api/v1/files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "url",
      "url": "https://example.com/image.png"
    },
    "file_name": "image.png"
  }'

const upload = await client.files.create({
  source: { type: 'url', url: 'https://example.com/image.png' },
  file_name: 'image.png'
});

Base64 示例

curl -X POST "https://runapi.ai/api/v1/files" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "base64",
      "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
    },
    "file_name": "image.png"
  }'

const upload = await client.files.create({
  source: {
    type: 'base64',
    data: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA...'
  },
  file_name: 'image.png'
});

CLI 示例

runapi files create ./image.png --file-name image.png
runapi files create --url https://example.com/image.png --file-name image.png
runapi files create --base64 "$BASE64_IMAGE" --file-name image.png

如果只需要把临时 URL 输出到 stdout，使用 --url-only：

runapi files create ./image.png --url-only

限制

响应

HTTP 201 - 创建成功：

{
  "file_name": "image.png",
  "url": "https://file.runapi.ai/temp/user-uploads/...",
  "size_bytes": 204800,
  "mime_type": "image/png",
  "created_at": "2026-06-08T10:30:00Z",
  "expires_at": "2026-06-08T11:30:00Z"
}

返回的 url 可用于任何需要输入文件 URL 的 RunAPI 参数，例如 source_image_url、source_image_urls 或 upload_url。

错误响应

错误示例：

{
  "error": {
    "code": "invalid_source",
    "message": "Only HTTPS URLs are allowed"
  }
}

Common

查询余额

获取当前账户余额与使用统计。

HTTP 请求

GET https://runapi.ai/api/v1/me/balance

鉴权

在 Authorization 头中包含 API Key：

Authorization: Bearer YOUR_API_TOKEN

请求示例

获取用户额度：

curl "https://runapi.ai/api/v1/me/balance" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

require 'net/http'
require 'uri'

uri = URI('https://runapi.ai/api/v1/me/balance')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN'
}

response = requests.get(
    'https://runapi.ai/api/v1/me/balance',
    headers=headers
)
print(response.json())

fetch('https://runapi.ai/api/v1/me/balance', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

响应

HTTP 200 - 成功：

{
  "balance_cents": 10000,
  "spent_cents_today": 150,
  "spent_cents_total": 5420
}

响应字段

错误响应

错误示例：

{
  "error": "Unauthorized"
}

说明

Management Keys

使用 Management Key 可以通过 API 以编程方式创建、查询、更新和撤销标准 API Key。

鉴权

在 Authorization 头中携带 Management Key：

Authorization: Bearer YOUR_MANAGEMENT_KEY

你可以在 Management Keys 页面 生成 Management Key。

查询 API Keys

HTTP 请求

GET https://runapi.ai/api/v1/keys

请求示例

curl "https://runapi.ai/api/v1/keys" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY"

响应

[
  {
    "name": "Production",
    "last_used_at": "2026-04-08T02:58:00Z",
    "created_at": "2026-04-08T02:58:00Z",
    "credit_limit_cents": 100,
    "credit_limit_reset_interval": "daily",
    "allowed_models": null,
    "enabled": true,
    "id": "token_123",
    "masked_token": "abcd••••••••wxyz",
    "guardrail_id": "guardrail_abc123"
  }
]

创建 API Key

HTTP 请求

POST https://runapi.ai/api/v1/keys

请求参数

参数 类型 必填 说明
name string 否 API Key 的友好名称
credit_limit_cents integer 否 单个 API Key 的消费上限，单位为美元分
credit_limit_reset_interval string 否 重置周期：daily、weekly 或 monthly
allowed_models string[] 否 限制此 API Key 可调用的模型集合，例如 ["gpt-5.4", "claude-opus-4-6"]。不传、传 null 或空数组表示不做限制。
enabled boolean 否 设为 false 时使用此 Key 的请求会返回 401 Unauthorized。默认 true。

如果传入 credit_limit_cents，则必须同时传入 credit_limit_reset_interval。

设置了 allowed_models 后，使用不在列表内的模型发起请求会被拒绝并返回 422 Unprocessable Content。

请求示例

curl -X POST "https://runapi.ai/api/v1/keys" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "credit_limit_cents": 100,
    "credit_limit_reset_interval": "daily",
    "allowed_models": ["gpt-5.4", "claude-opus-4-6"]
  }'

响应

{
  "name": "Production",
  "last_used_at": null,
  "created_at": "2026-04-08T02:58:00Z",
  "credit_limit_cents": 100,
  "credit_limit_reset_interval": "daily",
  "allowed_models": ["gpt-5.4", "claude-opus-4-6"],
  "enabled": true,
  "id": "token_123",
  "masked_token": "abcd••••••••wxyz",
  "guardrail_id": "guardrail_abc123",
  "key": "abcd1234efgh5678"
}

key 只会在创建成功时返回一次。

查询单个 API Key

HTTP 请求

GET https://runapi.ai/api/v1/keys/:id

请求示例

curl "https://runapi.ai/api/v1/keys/token_123" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY"

响应

{
  "name": "Production",
  "last_used_at": null,
  "created_at": "2026-04-08T02:58:00Z",
  "credit_limit_cents": 100,
  "credit_limit_reset_interval": "daily",
  "allowed_models": ["gpt-5.4", "claude-opus-4-6"],
  "enabled": true,
  "id": "token_123",
  "masked_token": "abcd••••••••wxyz",
  "guardrail_id": "guardrail_abc123",
  "credit_usage_cents_total": 25,
  "credit_usage_cents_today": 25,
  "credit_usage_cents_this_week": 25,
  "credit_usage_cents_this_month": 25
}

更新 API Key

HTTP 请求

PATCH https://runapi.ai/api/v1/keys/:id

请求示例

curl -X PATCH "https://runapi.ai/api/v1/keys/token_123" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production (rotated)",
    "credit_limit_cents": 500,
    "credit_limit_reset_interval": "weekly",
    "allowed_models": ["gpt-5.4"]
  }'

如果要清除限额，可以将 credit_limit_cents 设为 null 或空字符串。

allowed_models 在每次 PATCH 时会被绝对覆盖。传 null 或 [] 清空白名单；不传该字段则保持原有值不变。

传 "enabled": false 立即吊销此 Key 的认证，传 "enabled": true 重新启用。该字段独立于 credit_limit_cents，同一次请求里清空限额并禁用是允许的，两者会同时生效。

删除 API Key

HTTP 请求

DELETE https://runapi.ai/api/v1/keys/:id

请求示例

curl -X DELETE "https://runapi.ai/api/v1/keys/token_123" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY"

响应

HTTP 204 No Content

限额说明

Guardrails

Guardrails 是账号级别的可复用策略模板。可配置模型与提供商访问规则（白名单或黑名单）、总消耗上限，以及按模型设置的独立预算。每个 API key 或账号成员最多可绑定一个 guardrail；每次请求会独立校验 key 自身的限制和已绑定的 guardrail。

任意 Management Key 都可以在当前账号创建 guardrail。账号管理员可以更新或删除账号内任意 guardrail；普通 Management Key 只能更新或删除自己创建、且仅绑定到自己 API Key 的 guardrail。已经绑定到其他成员的 Key 或成员级绑定的 guardrail 需要管理员操作。

列出 Guardrails

GET https://runapi.ai/api/v1/guardrails

返回 {"guardrails": [...]}。

创建 Guardrail

POST https://runapi.ai/api/v1/guardrails

请求参数

字段 类型 必填 说明
name string 是 账号内唯一（大小写不敏感）
description string 否 描述
enabled boolean 否 默认 true
credit_limit_cents integer 否 该 guardrail 的总预算（USD 美分），必须与 credit_limit_reset_interval 同时提供
credit_limit_reset_interval string 否 daily / weekly / monthly
allowed_models string[] 否 模型白名单。空或 null 表示全部允许
blocked_models string[] 否 模型黑名单。优先于白名单
allowed_providers string[] 否 Provider 白名单（按名称）
blocked_providers string[] 否 Provider 黑名单（按名称）
model_budgets object[] 否 按模型范围计数的预算，每项：`{ "match_mode": "include"

model_budgets 只统计命中范围内的请求，不会拒绝范围外请求。include 只统计列出的模型；exclude 统计除列出模型以外的所有模型。exclude 对新模型更安全：未来新增模型默认会被计入受限预算，而不是默认绕过。

请求示例

curl -X POST "https://runapi.ai/api/v1/guardrails" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tier 1",
    "credit_limit_cents": 100000,
    "credit_limit_reset_interval": "monthly",
    "allowed_models": ["gpt-5.4", "claude-sonnet-4-6"],
    "model_budgets": [
      {
        "match_mode": "exclude",
        "models": ["gpt-5.4", "claude-sonnet-4-6"],
        "credit_limit_cents": 1000,
        "credit_limit_reset_interval": null
      }
    ]
  }'

返回 201 Created，响应体为 {"guardrail": {...}}。

获取 Guardrail

GET https://runapi.ai/api/v1/guardrails/:id

更新 Guardrail

PATCH https://runapi.ai/api/v1/guardrails/:id

账号管理员可以更新任意 guardrail。普通 Management Key 只能更新自己创建、且仅绑定到自己 API Key 的 guardrail。

标量字段在传入时被覆盖，未传入则保留原值。规则数组（allowed_models、blocked_models、allowed_providers、blocked_providers）和 model_budgets 在传入时为绝对替换，传 null 或 [] 表示清空，省略表示不变。

删除 Guardrail

DELETE https://runapi.ai/api/v1/guardrails/:id

账号管理员可以删除任意 guardrail。普通 Management Key 只能删除自己创建、且仅绑定到自己 API Key 的 guardrail。

软删除该 guardrail，并删除其全部绑定关系。返回 204 No Content，名称可被复用。

Guardrail Assignments

绑定一个 guardrail 到一个 API key 或一个账号成员。每个目标最多有一个直接绑定。

列出绑定

GET https://runapi.ai/api/v1/guardrail_assignments

返回 {"guardrail_assignments": [...]}。账号管理员可以看到全部，普通 Management Key 仅能看到自己 API Key 上的绑定。

创建绑定

POST https://runapi.ai/api/v1/guardrail_assignments

字段 类型 必填 说明
guardrail_id string 是 Guardrail 的 prefix ID
api_token_id string 二选一 API key 的 prefix ID
account_user_id string 二选一 账号成员的 prefix ID（仅管理员可用）

api_token_id 与 account_user_id 二选一。

权限

替换

要替换某个 key 或成员上的 guardrail，先 DELETE 现有 assignment，再创建新的。重复绑定会返回 422 Unprocessable Content。

删除绑定

DELETE https://runapi.ai/api/v1/guardrail_assignments/:id

返回 204 No Content。

错误

runapi.ai API 使用标准 HTTP 响应代码来指示请求的成功或失败。

HTTP 状态码

状态码 含义
200 OK - 请求成功
201 Created - 资源创建成功
400 Bad Request - 无效参数或格式错误的请求
401 Unauthorized - 无效或缺失的 API Key
402 Payment Required - 账户余额不足
403 Forbidden - API Key 有效但权限不足，或 API Key 已达到当前周期限额
404 Not Found - 资源不存在
422 Unprocessable Entity - 验证失败
429 Too Many Requests - 超过速率限制
500 Internal Server Error - 服务器端出现问题
503 Service Unavailable - 临时服务中断

错误响应格式

错误响应示例:

{
  "error": "Missing required parameter: prompt"
}

所有错误响应遵循简单的 JSON 格式,包含一个 error 字段,其中包含人类可读的错误消息。

常见错误消息

状态码 错误消息 说明
400 Missing required parameter: xxx 缺少必需参数
401 Unauthorized 无效或缺失的 API Key
402 Insufficient credits 账户余额不足
403 API key credit limit exceeded 该 API Key 已达到当前重置周期内配置的消费限额
404 Task not found 指定的任务不存在
404 Record does not exist 请求的资源不存在
408 Download timeout 文件下载超时
413 File size exceeds maximum allowed size 上传文件过大 (最大 10MB)
415 File type not supported 不支持的文件类型
422 Records are being generated 资源仍在处理中
500 Internal server error 服务器遇到错误

任务特定错误

当任务失败时,错误消息会包含在任务响应中:

{
  "id": "task-id",
  "status": "failed",
  "error": "Generation failed due to content policy violation"
}
cURL Ruby Python JavaScript