rw-api-reference

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Runway Public API Reference

Runway公共API参考

PREREQUISITE: Run
+rw-check-compatibility
first to ensure the project has server-side capability.

Base URL:

https://api.dev.runwayml.com

All requests require these headers:

Authorization: Bearer <RUNWAYML_API_SECRET>
X-Runway-Version: 2024-11-06

前提条件： 先运行
+rw-check-compatibility
，确保项目具备服务端能力。

基础URL：

https://api.dev.runwayml.com

所有请求均需包含以下请求头：

Authorization: Bearer <RUNWAYML_API_SECRET>
X-Runway-Version: 2024-11-06

Models & Endpoints

模型与端点

Video Generation

视频生成

Model	Endpoint	Input	Cost (credits/sec)
`gen4.5`	`POST /v1/image_to_video` or `POST /v1/text_to_video`	Text and/or Image	12
`gen4_turbo`	`POST /v1/image_to_video`	Image required	5
`gen4_aleph`	`POST /v1/video_to_video`	Video + Text/Image	15
`act_two`	`POST /v1/character_performance`	Image/Video	5
`veo3`	`POST /v1/image_to_video` or `POST /v1/text_to_video`	Text/Image	40
`veo3.1`	`POST /v1/image_to_video` or `POST /v1/text_to_video`	Text/Image	20-40
`veo3.1_fast`	`POST /v1/image_to_video` or `POST /v1/text_to_video`	Text/Image	10-15
`seedance2`	`POST /v1/text_to_video` , `POST /v1/image_to_video` , or `POST /v1/video_to_video`	Text, Image, and/or Video	36

Video duration: 2-15 seconds (model-dependent). Aspect ratios are pixel-based:

1280:720

720:1280

1104:832

960:960

832:1104

1584:672

, etc.

Seedance 2 specifics:

Modes: text-to-video, image-to-video (first/last frame or image reference), video-to-video
Duration: required for TTV and ITV (in seconds)

Aspect ratios (pixel-based):

1280:720

720:1280

960:960

1112:834

834:1112

1470:630

992:432

864:496

752:560

640:640

560:752

496:864

ITV supports two mutually exclusive modes: first/last frame (
```
promptImage
```
array with
```
position
```
) or image reference (
```
references
```
array)
VTV input requirements: max 15 seconds, max 32 MB, min 720p resolution, MP4 recommended

模型	端点	输入	成本（点数/秒）
`gen4.5`	`POST /v1/image_to_video` 或 `POST /v1/text_to_video`	文本和/或图像	12
`gen4_turbo`	`POST /v1/image_to_video`	必须提供图像	5
`gen4_aleph`	`POST /v1/video_to_video`	视频 + 文本/图像	15
`act_two`	`POST /v1/character_performance`	图像/视频	5
`veo3`	`POST /v1/image_to_video` 或 `POST /v1/text_to_video`	文本/图像	40
`veo3.1`	`POST /v1/image_to_video` 或 `POST /v1/text_to_video`	文本/图像	20-40
`veo3.1_fast`	`POST /v1/image_to_video` 或 `POST /v1/text_to_video`	文本/图像	10-15
`seedance2`	`POST /v1/text_to_video` 、 `POST /v1/image_to_video` 或 `POST /v1/video_to_video`	文本、图像和/或视频	36

视频时长：2-15秒（取决于模型）。宽高比基于像素：

1280:720

、

720:1280

、

1104:832

、

960:960

、

832:1104

、

1584:672

等。

Seedance 2 专属说明：

模式：文本转视频、图像转视频（首帧/末帧或图像参考）、视频转视频
时长：文本转视频和图像转视频需指定（单位：秒）

宽高比（基于像素）：

1280:720

、

720:1280

、

960:960

、

1112:834

、

834:1112

、

1470:630

、

992:432

、

864:496

、

752:560

、

640:640

、

560:752

、

496:864

图像转视频支持两种互斥模式：首帧/末帧（含
```
position
```
的
```
promptImage
```
数组）或图像参考（
```
references
```
数组）
视频转视频输入要求：最长15秒，最大32 MB，最低720p分辨率，推荐MP4格式

Image Generation

图像生成

Model	Endpoint	Cost (credits)
`gen4_image`	`POST /v1/text_to_image`	5 (720p), 8 (1080p)
`gen4_image_turbo`	`POST /v1/text_to_image`	2
`gemini_2.5_flash`	`POST /v1/text_to_image`	5

模型	端点	成本（点数）
`gen4_image`	`POST /v1/text_to_image`	5（720p）、8（1080p）
`gen4_image_turbo`	`POST /v1/text_to_image`	2
`gemini_2.5_flash`	`POST /v1/text_to_image`	5

Audio Generation

音频生成

Model	Endpoint	Use Case	Cost
`eleven_multilingual_v2`	`POST /v1/text_to_speech`	Text to speech	1 credit/50 chars
`eleven_text_to_sound_v2`	`POST /v1/sound_effect`	Sound effects	1-2 credits
`eleven_voice_isolation`	`POST /v1/voice_isolation`	Isolate voice from audio	1 credit/6 sec
`eleven_voice_dubbing`	`POST /v1/voice_dubbing`	Dub audio to other languages	1 credit/2 sec
`eleven_multilingual_sts_v2`	`POST /v1/speech_to_speech`	Voice conversion	1 credit/3 sec

模型	端点	使用场景	成本
`eleven_multilingual_v2`	`POST /v1/text_to_speech`	文本转语音	1点数/50字符
`eleven_text_to_sound_v2`	`POST /v1/sound_effect`	音效生成	1-2点数
`eleven_voice_isolation`	`POST /v1/voice_isolation`	从音频中分离人声	1点数/6秒
`eleven_voice_dubbing`	`POST /v1/voice_dubbing`	将音频配音为其他语言	1点数/2秒
`eleven_multilingual_sts_v2`	`POST /v1/speech_to_speech`	语音转换	1点数/3秒

Characters (Real-Time Avatars)

角色（实时虚拟形象）

Model	Description	Session Max Duration
`gwm1_avatars`	Real-time conversational avatars powered by GWM-1	5 minutes

Endpoints:

Method	Endpoint	Description
`POST`	`/v1/avatars`	Create a new Avatar
`GET`	`/v1/avatars/{id}`	Retrieve an Avatar
`PATCH`	`/v1/avatars/{id}`	Update an Avatar (name, voice, personality, documentIds)
`DELETE`	`/v1/avatars/{id}`	Delete an Avatar
`POST`	`/v1/realtime_sessions`	Create a new real-time session
`GET`	`/v1/realtime_sessions/{id}`	Retrieve session status (poll until `READY` )
`POST`	`/v1/realtime_sessions/{id}/consume`	Consume session credentials for WebRTC (one-time use)

Avatar creation parameters:

Parameter	Type	Description
`name`	string	Display name for the avatar
`referenceImage`	string	URL or `runway://` URI of the character image
`voice`	object	`{ type: 'runway-live-preset', presetId: 'clara' }`
`personality`	string	System prompt / personality instructions
`documentIds`	string[]	Optional. IDs of knowledge base documents to attach

Voice presets:

clara

(soft),

victoria

(firm),

vincent

(authoritative). Preview all at dev.runwayml.com.

Session statuses:

NOT_READY

→

READY

→

RUNNING

→

COMPLETED

(or

FAILED

CANCELLED

)

模型	描述	会话最长时长
`gwm1_avatars`	由GWM-1驱动的实时对话虚拟形象	5分钟

端点：

方法	端点	描述
`POST`	`/v1/avatars`	创建新虚拟形象
`GET`	`/v1/avatars/{id}`	获取虚拟形象信息
`PATCH`	`/v1/avatars/{id}`	更新虚拟形象（名称、语音、人设、documentIds）
`DELETE`	`/v1/avatars/{id}`	删除虚拟形象
`POST`	`/v1/realtime_sessions`	创建新实时会话
`GET`	`/v1/realtime_sessions/{id}`	获取会话状态（轮询直到状态为 `READY` ）
`POST`	`/v1/realtime_sessions/{id}/consume`	消耗会话凭证用于WebRTC（仅可使用一次）

虚拟形象创建参数：

参数	类型	描述
`name`	string	虚拟形象的显示名称
`referenceImage`	string	角色图像的URL或 `runway://` URI
`voice`	object	`{ type: 'runway-live-preset', presetId: 'clara' }`
`personality`	string	系统提示词/人设说明
`documentIds`	string[]	可选。需关联的知识库文档ID

语音预设：

clara

（柔和）、

victoria

（坚定）、

vincent

（权威）。可前往dev.runwayml.com预览全部预设。

会话状态：

NOT_READY

→

READY

→

RUNNING

→

COMPLETED

（或

FAILED

CANCELLED

）

Documents (Knowledge Base)

文档（知识库）

Method	Endpoint	Description
`POST`	`/v1/documents`	Create a document (plain text or Markdown)
`GET`	`/v1/documents/{id}`	Retrieve a document
`DELETE`	`/v1/documents/{id}`	Delete a document

Each Avatar supports up to 50,000 tokens of knowledge. Link documents to an Avatar via

client.avatars.update(id, { documentIds: [...] })

方法	端点	描述
`POST`	`/v1/documents`	创建文档（纯文本或Markdown格式）
`GET`	`/v1/documents/{id}`	获取文档信息
`DELETE`	`/v1/documents/{id}`	删除文档

每个虚拟形象最多支持50,000个token的知识库内容。可通过

client.avatars.update(id, { documentIds: [...] })

将文档关联到虚拟形象。

Request Body Reference (raw JSON)

请求体参考（原始JSON）

Use these when calling the API directly (e.g. through

use-runway-api

request

command) rather than via an SDK. Only required + common fields shown — consult

+rw-fetch-api-reference

for the full schema.

直接调用API时使用（例如通过

use-runway-api

的

request

命令），而非通过SDK。仅展示必填及常用字段——完整架构请参考

+rw-fetch-api-reference

。

POST /v1/text_to_image

POST /v1/text_to_image

json

{
  "model": "gen4_image",
  "promptText": "A serene Japanese garden with cherry blossoms",
  "ratio": "1920:1080"
}

model

gen4_image

gen4_image_turbo

gemini_2.5_flash

(required)

```
promptText
```
: string, up to ~1000 chars (required)

ratio

: one of

1920:1080

1080:1920

1024:1024

1360:768

1080:1080

1168:880

1440:1080

1080:1440

1808:768

2112:912

(required; 720p or 1080p variants depending on model)

referenceImages

: optional

[{ "uri": "https://...", "tag": "MyTag" }]

— reference by

@MyTag

promptText

```
seed
```
: optional integer for reproducibility

json

{
  "model": "gen4_image",
  "promptText": "A serene Japanese garden with cherry blossoms",
  "ratio": "1920:1080"
}

model

gen4_image

gen4_image_turbo

gemini_2.5_flash

（必填）

```
promptText
```
: 字符串，最多约1000字符（必填）
```
ratio
```
: 可选值包括
```
1920:1080
```
、
```
1080:1920
```
、
```
1024:1024
```
、
```
1360:768
```
、
```
1080:1080
```
、
```
1168:880
```
、
```
1440:1080
```
、
```
1080:1440
```
、
```
1808:768
```
、
```
2112:912
```
（必填；根据模型不同支持720p或1080p变体）

referenceImages

: 可选，格式为

[{ "uri": "https://...", "tag": "MyTag" }]

— 在

promptText

中通过

@MyTag

引用

```
seed
```
: 可选整数，用于生成结果可复现

POST /v1/text_to_video

POST /v1/text_to_video

json

{
  "model": "gen4.5",
  "promptText": "A golden retriever running through wildflowers at sunset",
  "ratio": "1280:720",
  "duration": 5
}

model

gen4.5

veo3

veo3.1

veo3.1_fast

seedance2

(required)

```
duration
```
: integer seconds, 2–10 (required; model-specific valid values — e.g. veo3 only accepts 8)

ratio

: e.g.

1280:720

720:1280

1104:832

832:1104

960:960

(required)

json

{
  "model": "gen4.5",
  "promptText": "A golden retriever running through wildflowers at sunset",
  "ratio": "1280:720",
  "duration": 5
}

model

gen4.5

veo3

veo3.1

veo3.1_fast

seedance2

（必填）

```
duration
```
: 整数，单位秒，范围2–10（必填；不同模型支持的有效值不同——例如veo3仅支持8秒）

ratio

: 例如

1280:720

、

720:1280

、

1104:832

、

832:1104

、

960:960

（必填）

POST /v1/image_to_video

POST /v1/image_to_video

json

{
  "model": "gen4.5",
  "promptImage": "https://example.com/cover.jpg",
  "promptText": "A slow dolly-in shot",
  "ratio": "1280:720",
  "duration": 5
}

model

gen4.5

gen4_turbo

veo3

veo3.1

veo3.1_fast

seedance2

(required)

promptImage

: HTTPS URL, data URI, or

runway://

URI (required). Can also be

[{ "uri": "...", "position": "first" | "last" }]

for keyframes.

```
promptText
```
: optional for most models, required for
```
gen4_turbo
```
when no image motion is obvious

json

{
  "model": "gen4.5",
  "promptImage": "https://example.com/cover.jpg",
  "promptText": "A slow dolly-in shot",
  "ratio": "1280:720",
  "duration": 5
}

model

gen4.5

gen4_turbo

veo3

veo3.1

veo3.1_fast

seedance2

（必填）

```
promptImage
```
: HTTPS URL、data URI或
```
runway://
```
URI（必填）。也可使用含关键帧的格式：
```
[{ "uri": "...", "position": "first" | "last" }]
```
```
promptText
```
: 多数模型可选，当图像无明显动态效果时，
```
gen4_turbo
```
必填

POST /v1/video_to_video

POST /v1/video_to_video

json

{
  "model": "gen4_aleph",
  "videoUri": "https://example.com/source.mp4",
  "promptText": "Change the season to winter with snowfall",
  "ratio": "1280:720"
}

json

{
  "model": "gen4_aleph",
  "videoUri": "https://example.com/source.mp4",
  "promptText": "Change the season to winter with snowfall",
  "ratio": "1280:720"
}

POST /v1/text_to_speech

POST /v1/text_to_speech

json

{
  "model": "eleven_multilingual_v2",
  "text": "Hello, welcome to Runway.",
  "voice": { "type": "runway-preset", "presetId": "clara" }
}

voice

{ type: "runway-preset", presetId: "clara" | "victoria" | "vincent" | ... }

or a provider-specific voice object

```
languageCode
```
: optional ISO code (auto-detected by default)

json

{
  "model": "eleven_multilingual_v2",
  "text": "Hello, welcome to Runway.",
  "voice": { "type": "runway-preset", "presetId": "clara" }
}

voice

{ type: "runway-preset", presetId: "clara" | "victoria" | "vincent" | ... }

或供应商专属语音对象

```
languageCode
```
: 可选ISO代码（默认自动检测）

POST /v1/sound_effect

POST /v1/sound_effect

json

{
  "model": "eleven_text_to_sound_v2",
  "promptText": "Thunderclap followed by heavy rain",
  "duration": 5
}

json

{
  "model": "eleven_text_to_sound_v2",
  "promptText": "Thunderclap followed by heavy rain",
  "duration": 5
}

POST /v1/voice_isolation

POST /v1/voice_isolation

json

{
  "model": "eleven_voice_isolation",
  "audioUri": "https://example.com/noisy.mp3"
}

json

{
  "model": "eleven_voice_isolation",
  "audioUri": "https://example.com/noisy.mp3"
}

POST /v1/voice_dubbing

POST /v1/voice_dubbing

json

{
  "model": "eleven_voice_dubbing",
  "audioUri": "https://example.com/english.mp3",
  "targetLanguage": "es"
}

json

{
  "model": "eleven_voice_dubbing",
  "audioUri": "https://example.com/english.mp3",
  "targetLanguage": "es"
}

POST /v1/speech_to_speech

POST /v1/speech_to_speech

json

{
  "model": "eleven_multilingual_sts_v2",
  "audioUri": "https://example.com/source.mp3",
  "voice": { "type": "runway-preset", "presetId": "victoria" }
}

json

{
  "model": "eleven_multilingual_sts_v2",
  "audioUri": "https://example.com/source.mp3",
  "voice": { "type": "runway-preset", "presetId": "victoria" }
}

POST /v1/avatars

POST /v1/avatars

json

{
  "name": "Support Agent",
  "referenceImage": "https://example.com/portrait.jpg",
  "voice": { "type": "runway-live-preset", "presetId": "clara" },
  "personality": "You are a friendly support agent.",
  "documentIds": []
}

json

{
  "name": "Support Agent",
  "referenceImage": "https://example.com/portrait.jpg",
  "voice": { "type": "runway-live-preset", "presetId": "clara" },
  "personality": "You are a friendly support agent.",
  "documentIds": []
}

POST /v1/documents

POST /v1/documents

json

{
  "avatarId": "<avatar-id>",
  "name": "FAQ",
  "content": "Q: What is your return policy?\nA: 30 days, no questions asked."
}

json

{
  "avatarId": "<avatar-id>",
  "name": "FAQ",
  "content": "Q: What is your return policy?\nA: 30 days, no questions asked."
}

POST /v1/realtime_sessions

POST /v1/realtime_sessions

json

{
  "avatarId": "<avatar-id>"
}

json

{
  "avatarId": "<avatar-id>"
}

Management Endpoints

管理端点

Method	Endpoint	Description
`GET`	`/v1/tasks/{id}`	Get task status and output
`DELETE`	`/v1/tasks/{id}`	Cancel/delete a task
`POST`	`/v1/uploads`	Create ephemeral upload
`GET`	`/v1/organization`	Organization info & credit balance
`POST`	`/v1/organization/usage`	Credit usage history (up to 90 days)

方法	端点	描述
`GET`	`/v1/tasks/{id}`	获取任务状态及输出
`DELETE`	`/v1/tasks/{id}`	取消/删除任务
`POST`	`/v1/uploads`	创建临时上传链接
`GET`	`/v1/organization`	组织信息及点数余额
`POST`	`/v1/organization/usage`	点数使用历史（最长90天）

Task Lifecycle

任务生命周期

All generation endpoints return a task object. The flow is:

Submit —
```
POST /v1/<endpoint>
```
→ returns
```
{ "id": "task_xxx" }
```
Poll —
```
GET /v1/tasks/{id}
```
→ returns task with
```
status
```
Retrieve output — When
```
status === "SUCCEEDED"
```
, the
```
output
```
array contains signed URLs

所有生成类端点均返回任务对象。流程如下：

提交 — 调用
```
POST /v1/<endpoint>
```
→ 返回
```
{ "id": "task_xxx" }
```
轮询 — 调用
```
GET /v1/tasks/{id}
```
→ 返回含
```
status
```
的任务信息
获取输出 — 当
```
status === "SUCCEEDED"
```
时，
```
output
```
数组包含签名URL

Task Statuses

任务状态

Status	Meaning
`PENDING`	Queued, waiting to start
`RUNNING`	Currently generating
`SUCCEEDED`	Complete — output URLs available
`FAILED`	Generation failed — check `failure` field
`THROTTLED`	Concurrency limit hit — auto-queued

状态	含义
`PENDING`	已排队，等待启动
`RUNNING`	正在生成
`SUCCEEDED`	生成完成 — 可获取输出URL
`FAILED`	生成失败 — 查看 `failure` 字段
`THROTTLED`	达到并发限制 — 自动排队

SDK Polling (Recommended)

SDK轮询（推荐）

The SDKs provide a

waitForTaskOutput()

method that handles polling automatically:

javascript

// Node.js — polls until complete (default 10 min timeout)
const task = await client.imageToVideo.create({
  model: 'gen4.5',
  promptImage: 'https://example.com/image.jpg',
  promptText: 'A sunset timelapse',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

console.log(task.output); // Array of signed URLs

python

undefined

SDK提供

waitForTaskOutput()

方法，可自动处理轮询：

javascript

// Node.js — 轮询直到完成（默认超时10分钟）
const task = await client.imageToVideo.create({
  model: 'gen4.5',
  promptImage: 'https://example.com/image.jpg',
  promptText: 'A sunset timelapse',
  ratio: '1280:720',
  duration: 5
}).waitForTaskOutput();

console.log(task.output); // 签名URL数组

python

undefined

Python

task = client.image_to_video.create( model='gen4.5', prompt_image='https://example.com/image.jpg', prompt_text='A sunset timelapse', ratio='1280:720', duration=5 ).wait_for_task_output()

print(task.output)

undefined

task = client.image_to_video.create( model='gen4.5', prompt_image='https://example.com/image.jpg', prompt_text='A sunset timelapse', ratio='1280:720', duration=5 ).wait_for_task_output()

print(task.output)

undefined

Manual Polling (REST)

手动轮询（REST）

javascript

async function pollTask(taskId) {
  while (true) {
    const response = await fetch(`https://api.dev.runwayml.com/v1/tasks/${taskId}`, {
      headers: {
        'Authorization': `Bearer ${process.env.RUNWAYML_API_SECRET}`,
        'X-Runway-Version': '2024-11-06'
      }
    });
    const task = await response.json();

    if (task.status === 'SUCCEEDED') return task;
    if (task.status === 'FAILED') throw new Error(task.failure);

    await new Promise(r => setTimeout(r, 5000)); // poll every 5 seconds
  }
}

javascript

async function pollTask(taskId) {
  while (true) {
    const response = await fetch(`https://api.dev.runwayml.com/v1/tasks/${taskId}`, {
      headers: {
        'Authorization': `Bearer ${process.env.RUNWAYML_API_SECRET}`,
        'X-Runway-Version': '2024-11-06'
      }
    });
    const task = await response.json();

    if (task.status === 'SUCCEEDED') return task;
    if (task.status === 'FAILED') throw new Error(task.failure);

    await new Promise(r => setTimeout(r, 5000)); // 每5秒轮询一次
  }
}

Output Handling

输出处理

Successful tasks return an
```
output
```
array with signed URLs to generated content
Output URLs expire within 24-48 hours
Download and store outputs in your own storage — do not serve signed URLs to end users
Video outputs are MP4, image outputs are PNG/JPEG

成功的任务返回
```
output
```
数组，包含生成内容的签名URL
输出URL会在24-48小时内过期
下载并将输出存储在自有存储中——不要将签名URL直接提供给终端用户
视频输出为MP4格式，图像输出为PNG/JPEG格式

Input Requirements

输入要求

Size Limits

大小限制

Type	Via URL	Via Data URI	Via Upload
Image	16 MB	5 MB	200 MB
Video	32 MB	16 MB	200 MB
Audio	32 MB	16 MB	200 MB

类型	通过URL	通过Data URI	通过上传
图像	16 MB	5 MB	200 MB
视频	32 MB	16 MB	200 MB
音频	32 MB	16 MB	200 MB

Supported Formats

支持的格式

Images: JPEG, PNG, WebP (no GIF)
Video codecs: H.264, H.265/HEVC, AV1, VP8/VP9, Apple ProRes, Theora
Audio: MP3, AAC, FLAC, PCM, ALAC

图像： JPEG、PNG、WebP（不支持GIF）
视频编码： H.264、H.265/HEVC、AV1、VP8/VP9、Apple ProRes、Theora
音频： MP3、AAC、FLAC、PCM、ALAC

URL Requirements

URL要求

If providing assets via URL:

HTTPS only (no HTTP)
Domain names only (no IP addresses)
No redirects
Must support HTTP HEAD requests
Must return valid
```
Content-Type
```
and
```
Content-Length
```
headers
Max URL length: 2,048 characters

若通过URL提供资源：

仅支持HTTPS（不支持HTTP）
仅支持域名（不支持IP地址）
无重定向
必须支持HTTP HEAD请求
必须返回有效的
```
Content-Type
```
和
```
Content-Length
```
请求头
URL最大长度：2048字符

Rate Limits & Tiers

速率限制与等级

Tier	Concurrency	Daily Gens	Monthly Cap	Unlock
1 (default)	1-2	50-200	$100	—
2	3	500-1,000	$500	1 day + $50
3	5	1,000-2,000	$2,000	7 days + $100
4	10	5,000-10,000	$20,000	14 days + $1,000
5	20	25,000-30,000	$100,000	7 days + $5,000

No requests-per-minute limit — only daily generation quotas
Exceeding concurrency →
```
THROTTLED
```
status (auto-queued, not rejected)
Exceeding daily limit →
```
429 Too Many Requests
```
Daily limits use a rolling 24-hour window

等级	并发数	每日生成量	月度上限	解锁条件
1（默认）	1-2	50-200	100美元	—
2	3	500-1000	500美元	1天 + 50美元
3	5	1000-2000	2000美元	7天 + 100美元
4	10	5000-10000	20000美元	14天 + 1000美元
5	20	25000-30000	100000美元	7天 + 5000美元

无每分钟请求数限制——仅限制每日生成配额
超过并发数→返回
```
THROTTLED
```
状态（自动排队，不会被拒绝）
超过每日限制→返回
```
429 Too Many Requests
```
每日限制采用滚动24小时窗口

Error Handling

错误处理

HTTP Errors

HTTP错误

Code	Meaning	Action
400	Input validation failure	Fix input, do not retry
401	Invalid API key	Check key, do not retry
429	Rate limited	Retry with exponential backoff + jitter
502/503/504	Server overload	Retry with exponential backoff + jitter

状态码	含义	操作
400	输入验证失败	修正输入，请勿重试
401	API密钥无效	检查密钥，请勿重试
429	速率限制	使用指数退避+抖动策略重试
502/503/504	服务器过载	使用指数退避+抖动策略重试

Task Failure Codes

任务失败代码

Code	Meaning	Retry?
`SAFETY.INPUT.*`	Input content moderation	No — not refundable
`SAFETY.OUTPUT.*`	Output content moderation	Yes — try different prompt
`INTERNAL.BAD_OUTPUT`	Quality issue	Yes
`ASSET.INVALID`	Bad input format	Fix input
`INTERNAL`	Server error	Yes

The SDKs handle retries for transient errors automatically.

代码	含义	是否可重试？
`SAFETY.INPUT.*`	输入内容审核不通过	否 — 不予退款
`SAFETY.OUTPUT.*`	输出内容审核不通过	是 — 尝试更换提示词
`INTERNAL.BAD_OUTPUT`	生成质量问题	是
`ASSET.INVALID`	输入格式错误	修正输入
`INTERNAL`	服务器错误	是

SDK会自动处理临时错误的重试。

Data URI Support

Data URI支持

Base64-encoded images can be passed instead of URLs:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

Useful for small images or when you don't want to host the file. Subject to the data URI size limits above.

可传入Base64编码的图像替代URL：

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

适用于小型图像或无需托管文件的场景。需遵守上述Data URI大小限制。