Claude API 概览Claude API Overview

通过 StoryClaw 中转接入 Claude 大语言模型，无需科学上网。接口兼容 Anthropic 官方 SDK，替换 Base URL 后即可使用。

Access Claude LLMs via StoryClaw relay — no VPN required. Compatible with the official Anthropic SDK. Just swap the base URL.

🌐

接口地址Base URL

https://router.storyclaw.com

所有 Claude API 请求均发往此地址。

All Claude API requests go to this URL.

🔑

认证方式Authentication

Authorization: Bearer YOUR_API_KEY

在请求头中传递 API Key，格式固定为 Bearer Token。

Pass your API Key in the request header as a Bearer Token.

⚡

支持模型Supported Models

claude-opus-4-7 claude-opus-4-6 claude-sonnet-4-6

1

获取 API KeyGet an API Key

前往控制台 → API Keys 创建密钥，格式为 sk-xxxxxxxx。

Go to Dashboard → API Keys to create a key. Format: sk-xxxxxxxx.

2

安装 SDKInstall SDK

使用官方 Anthropic SDK，Python：pip install anthropic；Node.js：

npm
                install @anthropic-ai/sdk

。

Use the official Anthropic SDK. Python: pip install anthropic · Node.js: npm install @anthropic-ai/sdk.

3

替换 Base URLSet Base URL

初始化 SDK 时将 base_url 设为 https://router.storyclaw.com，其他用法与官方完全一致。

Set base_url to https://router.storyclaw.com when initializing the SDK. Everything else is identical to the official Anthropic API.

安全提示Security — 切勿将 API Key 提交到公开代码仓库，如密钥泄露请立即在控制台重新生成。 — Never commit your API Key to a public repository. Regenerate it immediately if leaked.

Python
import anthropic

# 将 base_url 替换为 StoryClaw 中转地址
client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://router.storyclaw.com",
)

msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
print(msg.content[0].text)
            

Node.js
import Anthropic from '@anthropic-ai/sdk';

// 将 baseURL 替换为 StoryClaw 中转地址
const client = new Anthropic({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://router.storyclaw.com',
});

const msg = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(msg.content[0].text);
            

cURL
curl --request POST \
  --url https://router.storyclaw.com/v1/messages \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role":"user","content":"Hello!"}]
  }'
            

Anthropic消息接口Anthropic Messages

向 Claude 发送对话消息，同步获得回复。支持多轮对话、系统提示词与流式输出（SSE）。

Send messages to Claude and receive responses synchronously. Supports multi-turn conversations, system prompts, and streaming (SSE).

POST https://router.storyclaw.com/v1/messages

认证Authorization

Authorization string header required

Bearer Token 认证，值为 Bearer YOUR_API_KEY

Body application/json

modelenum<string>required

模型名称。Model identifier.

claude-opus-4-7 claude-opus-4-6 claude-sonnet-4-6

messagesarrayrequired

对话消息列表，每条含 role（user 或 assistant）与 content（字符串）。

Conversation messages. Each has role (user/assistant) and content (string).

max_tokensintegerrequired

最大生成 Token 数，通常 1024–16384，不同模型上限不同。

Maximum tokens to generate. Typically 1024–16384, varies by model.

systemstringoptional

系统提示词，定义模型角色与行为。

System prompt to define the model's role and behavior.

temperaturenumberoptionaldefault: 1

采样温度 0–1，越高输出越随机，0 为确定性。

Sampling temperature 0–1. Higher = more random; 0 = deterministic.

streambooleanoptionaldefault: false

开启 SSE 流式输出，适合实时展示场景。

Enable SSE streaming for real-time display.

响应Response

idstring

消息唯一 ID，格式 Message ID, format msg_xxxxxxxx

contentarray

返回内容块，通常为 [{type:"text", text:"..."}]

Content blocks, typically [{type:"text", text:"..."}]

stop_reasonenum

end_turnmax_tokensstop_sequence

usageobject

input_tokens & output_tokens

请求示例Request

              
              
              
            
curl --request POST \
  --url https://router.storyclaw.com/v1/messages \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
            
import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="https://router.storyclaw.com",
)
msg = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You are a helpful assistant.",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(msg.content[0].text)
            
const client = new Anthropic({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://router.storyclaw.com',
});
const msg = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(msg.content[0].text);
            

响应示例Response
200 OKapplication/json
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    { "type": "text", "text": "Hello! How can I help?" }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 12, "output_tokens": 18 }
}
            

Gemini消息接口Gemini Messages

向 Gemini 发送对话内容，同步获得生成结果。请求体使用 Google Gemini generateContent 格式，支持文本 parts 与生成参数配置。

Send conversational content to Gemini and receive generated output synchronously. The request body follows Google Gemini's generateContent format with text parts and generation settings.

POST https://router.storyclaw.com/models/{model}:generateContent

路径参数Path Parameters

modelenum<string>required

Gemini 模型名称。Gemini model identifier.

gemini-3-flash-preview gemini-3.1-flash-lite gemini-3.1-pro-preview gemini-3.5-flash

认证Authorization

Authorization string header required

Bearer Token 认证，值为 Bearer YOUR_API_KEY

Body application/json

contentsarrayrequired

对话内容列表，每条含 role（如 user 或 model）与 parts 数组。

Conversation contents. Each item has a role such as user or model, plus a parts array.

contents[].parts[].textstringrequired

文本输入内容，可用于单轮或多轮对话。

Text input for single-turn or multi-turn conversations.

generationConfigobjectoptional

生成参数配置对象，用于控制输出长度与采样行为。

Generation settings used to control output length and sampling behavior.

generationConfig.temperaturenumberoptional

采样温度，越高输出越随机；示例使用 0.7。

Sampling temperature. Higher values produce more varied output. The example uses 0.7.

generationConfig.maxOutputTokensintegeroptional

最大生成 Token 数，示例使用 256。

Maximum output tokens. The example uses 256.

响应Response

candidates[].content.parts[].textstring

模型生成的文本内容。

Generated text returned by the model.

candidates[].finishReasonenum

STOPMAX_TOKENSSAFETY

usageMetadataobject

promptTokenCount, candidatesTokenCount & totalTokenCount

请求示例Request

              
            
curl --location 'https://router.storyclaw.com/models/{model}:generateContent' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "你好，请用一句话介绍你自己。" }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 256
    }
  }'
            

响应示例Response
200 OKapplication/json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "你好！我是 Gemini，可以帮助你进行文本生成、理解和创作。" }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 18,
    "totalTokenCount": 30
  }
}
            

OpenAI消息接口OpenAI Messages

向 OpenAI 兼容的 Chat Completions 接口发送对话消息，同步获得回复。请求体使用 messages 格式，适合从 OpenAI SDK 或现有 Chat Completions 调用迁移。

Send conversation messages to the OpenAI-compatible Chat Completions endpoint and receive a synchronous response. The request body uses the messages format for easy migration from existing OpenAI SDK or Chat Completions calls.

POST https://router.storyclaw.com/chat/completions

认证Authorization

Authorization string header required

Bearer Token 认证，值为 Bearer YOUR_API_KEY

Body application/json

modelenum<string>required

OpenAI 模型名称。OpenAI model identifier.

gpt-5.4 gpt-5.5

messagesarrayrequired

对话消息列表，每条含 role（如 system、user 或 assistant）与 content（字符串）。

Conversation messages. Each item has a role such as system, user, or assistant, plus string content.

max_tokensintegeroptional

最大生成 Token 数，示例使用 8192。

Maximum output tokens. The example uses 8192.

响应Response

idstring

请求返回的唯一 ID。Unique ID returned for the request.

choices[].message.contentstring

模型生成的文本内容。

Generated text returned by the model.

choices[].finish_reasonenum

stoplengthcontent_filter

usageobject

prompt_tokens, completion_tokens & total_tokens

请求示例Request

              
            
curl --location 'https://router.storyclaw.com/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {"role": "user", "content": "Say ping in one word."}
    ],
    "max_tokens": 8192
  }'
            

响应示例Response
200 OKapplication/json
{
  "id": "chatcmpl_01H8YxK4n9qP",
  "object": "chat.completion",
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "ping"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 1,
    "total_tokens": 15
  }
}
            

Seedance 2.0 概览Seedance 2.0 Overview

Seedance 2.0 是字节跳动推出的高质量视频生成模型，通过 StoryClaw 接入支持文生视频、图生视频和多模态 OmniVideo 三种生成模式。

Seedance 2.0 is ByteDance's high-quality video generation model. Via StoryClaw, it supports Text-to-Video, Image-to-Video, and multi-modal OmniVideo generation.

🌐

接口地址Base URL

https://models.storyclaw.com

所有 Seedance 视频任务均通过此地址提交。

All Seedance video tasks are submitted to this URL.

🔑

认证方式Authentication

Authorization: Bearer YOUR_API_KEY

与 Claude API 使用同一个 API Key。

Uses the same API Key as the Claude API.

⚙️

处理模式Processing Model

异步任务Async Task

提交任务后返回 task_id，通过查询接口轮询状态直到完成（status = 2）。视频链接有效期通常为 24 小时，请及时保存。

Submit a task to get a task_id, then poll the query endpoint until status = 2 (completed). Video URLs typically expire in 24 hours — save them promptly.

任务状态码Task Status Codes

0

排队中 — 任务已提交，等待调度Queued — submitted, waiting to be scheduled

1

处理中 — 模型正在生成视频Processing — model is generating the video

2

已完成 — 结果 URL 可用Completed — result URL is available

3

失败 — 请查看 error_msg 字段Failed — check the error_msg field

典型调用流程Typical Flow
# Step 1: 提交任务
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{"task":"Txt2Video","model":"seedance-2.0-pro","mode":"pro","input":{...}}'

# Response → 获得 task_id
{ "code": 200, "task_id": "Txt2Video_seedance-2.0-pro_xxx" }

# Step 2: 轮询任务状态（每 3-5 秒一次）
curl --request GET \
  --url https://models.storyclaw.com/v1/router/tasks/Txt2Video_seedance-2.0-pro_xxx \
  --header 'Authorization: Bearer YOUR_API_KEY'

# status=2 时任务完成
{
  "status": 2,
  "results": [{ "urls": ["https://static.giggle.pro/.../video.mp4"] }]
}
            

Python 轮询示例Polling Example
import requests, time

BASE = "https://models.storyclaw.com"
HDR = {"Authorization": "Bearer YOUR_API_KEY"}

# 提交任务
res = requests.post(f"{BASE}/v1/router/task/create",
    headers=HDR,
    json={"task": "Txt2Video", "model": "seedance-2.0-pro",
          "mode": "pro", "input": {"prompt": "A sunrise",
          "duration": 6, "aspect_ratio": "16:9"}}
)
task_id = res.json()["task_id"]

# 轮询直到完成
while True:
    r = requests.get(f"{BASE}/v1/router/tasks/{task_id}", headers=HDR)
    data = r.json()
    if data["status"] == 2:
        print("Done:", data["results"][0]["urls"])
        break
    elif data["status"] == 3:
        print("Failed"); break
    time.sleep(5)
            

创建资产

上传图片、视频或音频素材为 Seedance 任务资产。传入文件直链与资产元信息，任务完成后可在后续生成任务中引用。

Upload image, video, or audio files as Seedance task assets. Provide a direct file URL and asset metadata so the uploaded asset can be referenced by later generation tasks.

POST https://models.storyclaw.com/v1/router/task/create

Body application/json

taskstringrequired

固定传 FileUpload

Always pass FileUpload.

modelstringrequired

ark-upload

modestringrequired

固定传 pro

Always pass pro.

callback_urlstring<uri>optional

任务完成后的 HTTPS 回调地址，为空则需主动轮询。

HTTPS callback URL on completion. If empty, poll manually.

input.filestring<uri>required

要上传的文件 URL。请传公开可直接访问的文件直链，不传文件内容。

File URL to upload. Pass a publicly accessible direct file URL, not file content.

input.pass_through.groupidstringrequired

固定传 group-20260610155306-lgw6l

Always pass group-20260610155306-lgw6l.

input.pass_through.namestringrequired

资产名称，根据上传文件填写。

Asset name. Set this based on the uploaded file.

input.pass_through.assettypeenum<string>required

资产类型，根据上传文件填写。

Asset type. Set this based on the uploaded file.

ImageVideoAudio

input.pass_through.Moderation.Strategystringrequired

固定传 Skip

Always pass Skip.

文件要求File Requirements

Imageassettype

格式：Formats: jpeg png webp bmp tiff gif heic/heif
宽高比（W/H）：0.4 ~ 2.5Aspect ratio (W/H): 0.4 ~ 2.5
宽/高：300 ~ 6000 pxWidth/height: 300 ~ 6000 px
大小：单张 < 30MBSize: < 30MB per image

Videoassettype

格式：Formats: mp4 mov
分辨率：480p、720p、1080pResolution: 480p, 720p, 1080p
时长：2 ~ 15 秒Duration: 2 ~ 15 seconds
宽高比（W/H）：0.4 ~ 2.5Aspect ratio (W/H): 0.4 ~ 2.5
宽/高：300 ~ 6000 pxWidth/height: 300 ~ 6000 px
总像素（W×H）：409600 ~ 2086876Total pixels (W×H): 409600 ~ 2086876
大小：单个视频 ≤ 50MBSize: ≤ 50MB per video
FPS：24 ~ 60FPS: 24 ~ 60

Audioassettype

格式：Formats: wav mp3
时长：2 ~ 15 秒Duration: 2 ~ 15 seconds
大小：单个音频 ≤ 15MBSize: ≤ 15MB per audio

响应（200 OK）Response (200 OK)

codeinteger

200 = 上传任务创建成功upload task created successfully

task_idstring

用于查询上传任务状态。

Used to query the upload task status.

请求示例Request

              
              
            
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "FileUpload",
    "model": "ark-upload",
    "mode": "pro",
    "callback_url": "",
    "input": {
      "file": "https://hs.17hd.com/duan.wav",
      "pass_through": {
        "groupid": "group-20260610155306-lgw6l",
        "name": "Cobra Test Audio",
        "assettype": "Audio",
        "Moderation": {
          "Strategy": "Skip"
        }
      }
    }
  }'
            
import requests

res = requests.post(
    "https://models.storyclaw.com/v1/router/task/create",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "task": "FileUpload",
        "model": "ark-upload",
        "mode": "pro",
        "callback_url": "",
        "input": {
            "file": "https://hs.17hd.com/duan.wav",
            "pass_through": {
                "groupid": "group-20260610155306-lgw6l",
                "name": "Cobra Test Audio",
                "assettype": "Audio",
                "Moderation": {"Strategy": "Skip"},
            },
        },
    },
)
print(res.json()["task_id"])
            

响应Response
200 OK
{
  "code": 200,
  "message": "task created",
  "task_id": "FileUpload_ark-upload_207df23e-6a1d-41b2-b7aa-ab0c535b1db0"
}
            

文生视频Text to Video

根据文字描述生成视频，支持 4–10 秒时长、多种画幅比例与分辨率。

Generate video from a text prompt. Supports 4–10 second duration, multiple aspect ratios, and resolutions.

POST https://models.storyclaw.com/v1/router/task/create

Body application/json

taskstringrequired

固定传 Txt2Video

modelenum<string>required

seedance-2.0-pro

modestringrequired

固定传 pro

callback_urlstring<uri>optional

任务完成后的 HTTPS 回调地址，为空则需主动轮询。

HTTPS callback URL on completion. If empty, poll manually.

input.promptstringrequired

视频描述，越详细效果越好，可描述镜头运动、场景、风格等。

Video description. Be specific — include camera movement, scene, style for best results.

input.durationintegerrequired

时长（秒）

Duration in seconds

46810

input.aspect_ratioenum<string>required

16:99:161:14:3

input.resolutionenum<string>optionaldefault: 720p

720p1080p

input.generate_audiobooleanoptionaldefault: false

是否自动生成配音/音效

Auto-generate audio/sound effects

响应（200 OK）Response (200 OK)

codeinteger

200 = 任务创建成功task created successfully

task_idstring

格式 Txt2Video_{model}_{uuid}，用于查询和取消。

Format: Txt2Video_{model}_{uuid}, used to query or cancel.

请求示例Request

              
              
            
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Txt2Video",
    "model": "seedance-2.0-pro",
    "mode": "pro",
    "callback_url": "",
    "input": {
      "prompt": "相机缓缓向前推进，人物在画面中微笑",
      "duration": 6,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true
    }
  }'
            
import requests

res = requests.post(
    "https://models.storyclaw.com/v1/router/task/create",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "task": "Txt2Video", "model": "seedance-2.0-pro",
        "mode": "pro", "callback_url": "",
        "input": {
            "prompt": "相机缓缓向前推进，人物在画面中微笑",
            "duration": 6, "aspect_ratio": "16:9",
            "resolution": "720p", "generate_audio": True,
        },
    }
)
print(res.json()["task_id"])
            

响应Response
200 OK
{
  "code": 200,
  "message": "task created",
  "task_id": "Txt2Video_seedance-2.0-pro_207df23e-6a1d-41b2-b7aa-ab0c535b1db0"
}
            

图生视频Image to Video

以图片为首帧，结合文字描述生成视频，适合产品展示、角色动画等。

Use an image as the first frame and generate video from a text prompt. Ideal for product showcases and character animation.

POSThttps://models.storyclaw.com/v1/router/task/create

Body application/json

taskstringrequired

固定传 Img2Video

modelenumrequired

seedance-2.0-pro

input.promptstringrequired

描述图片如何运动或演变。

Describe how the image should animate or evolve.

input.imagesstring[]required

首帧图片 URL 列表，必须为公开可直接访问的链接。

First-frame image URL list. Must be publicly accessible direct links.

支持格式：Formats: .jpg .png .webp
单张 ≤ 20MBMax 20MB per image

input.durationintegerrequired

468

input.aspect_ratioenumrequired

16:99:161:1

input.resolutionenumoptional

720p1080p

input.generate_audiobooleanoptional

自动生成音效

Auto-generate audio

callback_urlstring<uri>optional

HTTPS 回调地址

HTTPS callback URL

请求示例Request

              
              
            
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Img2Video",
    "model": "seedance-2.0-pro",
    "mode": "pro",
    "callback_url": "",
    "input": {
      "prompt": "A conductor leads an orchestra joyfully",
      "images": ["https://example.com/frame.jpg"],
      "duration": 4,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true
    }
  }'
            
import requests

res = requests.post(
    "https://models.storyclaw.com/v1/router/task/create",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "task": "Img2Video", "model": "seedance-2.0-pro",
        "mode": "pro", "callback_url": "",
        "input": {
            "prompt": "A conductor leads an orchestra",
            "images": ["https://example.com/frame.jpg"],
            "duration": 4, "aspect_ratio": "16:9",
            "resolution": "720p", "generate_audio": True,
        },
    }
)
print(res.json()["task_id"])
            

响应Response
200 OK
{ "code": 200, "message": "task created",
  "task_id": "Img2Video_seedance-2.0-pro_207df23e..." }
            

OmniVideo

多模态视频生成，可同时传入图片、音频、参考视频，最长 10 秒，适合广告、品牌 MV 等专业场景。

Multi-modal video generation. Accepts images, audio, and reference videos simultaneously. Up to 10 seconds. Ideal for ads and brand music videos.

POSThttps://models.storyclaw.com/v1/router/task/create

Body application/json

taskstringrequired

固定传 OmniVideo

input.promptstringrequired

详细描述内容、时序与镜头运动，通过"图片1"、"音频1"、"视频1"引用媒体素材。

Describe content, timing, and camera movement. Reference media as "image1", "audio1", "video1".

input.imagesstring[]optional

参考图片 URL 列表

Reference image URLs

input.audiosstring[]optional

参考音频 URL 列表（MP3/WAV）

Reference audio URLs (MP3/WAV)

input.videosstring[]optional

参考视频 URL，用于镜头风格参考

Reference video URLs for style/composition guidance

input.durationintegerrequired

时长（秒），最大 10

Duration in seconds, max 10

input.ratioenumrequired

16:99:161:1

input.generate_audiobooleanoptional

是否生成配音，配合音频参考效果更佳

Generate audio. Works best with audio reference files

提示Tip — 在 prompt 中用"第0-3秒"、"第4-6秒"等时间段描述各段内容，结合媒体引用可实现精确的叙事控制。 — Structure the prompt with time segments ("0-3s", "4-6s") combined with media references for precise narrative control.

请求示例Request

              
            
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "OmniVideo",
    "model": "seedance-2.0-pro",
    "mode": "pro",
    "callback_url": "",
    "input": {
      "prompt": "全程使用音频1作为背景音乐。0-3秒：图片1的苹果特写；4-6秒：快速切镜摇晃果茶；尾帧定格为图片2。",
      "images": [
        "https://example.com/apple.jpg",
        "https://example.com/drink.jpg"
      ],
      "audios": ["https://example.com/bgm.mp3"],
      "videos": ["https://example.com/ref.mp4"],
      "duration": 10,
      "ratio": "16:9",
      "generate_audio": true
    }
  }'
            

响应Response
200 OK
{ "code": 200, "message": "task created",
  "task_id": "Img2Video_seedance-2.0-pro_207df23e..." }
            

Kling V2.6 概览Kling V2.6 Overview

Kling V2.6 是快手可灵推出的视频生成模型，支持从文字或图片生成高质量视频，并提供音画同步的一体化生成能力。

Kling V2.6 is Kuaishou Kling's video generation model for creating high-quality videos from text or images, with integrated audio-video generation capabilities.

🌐

接口地址Base URL

https://models.storyclaw.com

所有 Kling V2.6 视频任务均通过此地址提交。

All Kling V2.6 video tasks are submitted to this URL.

🔑

认证方式Authentication

Authorization: Bearer YOUR_API_KEY

与 Claude API 使用同一个 API Key。

Uses the same API Key as the Claude API.

⚙️

处理模式Processing Model

异步任务Async Task

提交任务后返回 task_id，通过查询接口轮询状态直到完成（status = 2）。视频链接有效期通常为 24 小时，请及时保存。

Submit a task to get a task_id, then poll the query endpoint until status = 2 (completed). Video URLs typically expire in 24 hours — save them promptly.

任务状态码Task Status Codes

0

排队中 — 任务已提交，等待调度Queued — submitted, waiting to be scheduled

1

处理中 — 模型正在生成视频Processing — model is generating the video

2

已完成 — 结果 URL 可用Completed — result URL is available

3

失败 — 请查看 error_msg 字段Failed — check the error_msg field

典型调用流程Typical Flow
# Step 1: 提交任务
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{"task":"Txt2Video","model":"kling-v2-6","mode":"pro","input":{...}}'

# Response → 获得 task_id
{ "code": 200, "task_id": "Txt2Video_kling-v2-6_xxx" }

# Step 2: 轮询任务状态（每 3-5 秒一次）
curl --request GET \
  --url https://models.storyclaw.com/v1/router/tasks/Txt2Video_kling-v2-6_xxx \
  --header 'Authorization: Bearer YOUR_API_KEY'

# status=2 时任务完成
{
  "status": 2,
  "results": [{ "urls": ["https://static.giggle.pro/.../video.mp4"] }]
}
            

Python 轮询示例Polling Example
import requests, time

BASE = "https://models.storyclaw.com"
HDR = {"Authorization": "Bearer YOUR_API_KEY"}

# 提交任务
res = requests.post(f"{BASE}/v1/router/task/create",
    headers=HDR,
    json={"task": "Txt2Video", "model": "kling-v2-6",
          "mode": "pro", "input": {"prompt": "A sunrise",
          "duration": 6, "aspect_ratio": "16:9"}}
)
task_id = res.json()["task_id"]

# 轮询直到完成
while True:
    r = requests.get(f"{BASE}/v1/router/tasks/{task_id}", headers=HDR)
    data = r.json()
    if data["status"] == 2:
        print("Done:", data["results"][0]["urls"])
        break
    elif data["status"] == 3:
        print("Failed"); break
    time.sleep(5)
            

文生视频Text to Video

根据文字描述生成视频，支持 5 或 10 秒时长，以及 16:9、9:16、1:1 画幅比例。

Generate video from a text prompt. Supports 5 or 10 second duration and 16:9, 9:16, 1:1 aspect ratios.

POST https://models.storyclaw.com/v1/router/task/create

Body application/json

taskstringrequired

固定传 Txt2Video

modelenum<string>required

kling-v2-6

modestringrequired

固定传 pro

callback_urlstring<uri>optional

任务完成后的 HTTPS 回调地址，为空则需主动轮询。

HTTPS callback URL on completion. If empty, poll manually.

input.promptstringrequired

视频描述，越详细效果越好，可描述镜头运动、场景、风格等。

Video description. Be specific — include camera movement, scene, style for best results.

input.durationstringoptionaldefault: 5

视频长度，单位：秒。

Video length in seconds.

510

input.aspect_ratiostringoptionaldefault: 16:9

生成视频帧的宽高比（宽:高）。

Generated video frame aspect ratio (width:height).

16:99:161:1

input.generate_audiobooleanoptionaldefault: false

是否自动生成配音/音效

Auto-generate audio/sound effects

响应（200 OK）Response (200 OK)

codeinteger

200 = 任务创建成功task created successfully

task_idstring

格式 Txt2Video_{model}_{uuid}，用于查询和取消。

Format: Txt2Video_{model}_{uuid}, used to query or cancel.

请求示例Request

              
              
            
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Txt2Video",
    "model": "kling-v2-6",
    "mode": "pro",
    "callback_url": "",
    "input": {
      "prompt": "相机缓缓向前推进，人物在画面中微笑",
      "duration": "5",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'
            
import requests

res = requests.post(
    "https://models.storyclaw.com/v1/router/task/create",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "task": "Txt2Video", "model": "kling-v2-6",
        "mode": "pro", "callback_url": "",
        "input": {
            "prompt": "相机缓缓向前推进，人物在画面中微笑",
            "duration": "5", "aspect_ratio": "16:9",
            "generate_audio": True,
        },
    }
)
print(res.json()["task_id"])
            

响应Response
200 OK
{
  "code": 200,
  "message": "task created",
  "task_id": "Txt2Video_kling-v2-6_207df23e-6a1d-41b2-b7aa-ab0c535b1db0"
}
            

图生视频Image to Video

以图片为首帧，结合文字描述生成视频，适合产品展示、角色动画等。

Use an image as the first frame and generate video from a text prompt. Ideal for product showcases and character animation.

POSThttps://models.storyclaw.com/v1/router/task/create

Body application/json

taskstringrequired

固定传 Img2Video

modelenumrequired

kling-v2-6

input.promptstringrequired

描述图片如何运动或演变。

Describe how the image should animate or evolve.

input.imagesstring[]required

首尾帧图片 URL 列表，最多 2 张，必须为公开可直接访问的链接。第一张为首帧，第二张为尾帧。图片格式支持 .jpg / .jpeg / .png；文件大小不能超过 10MB；图片宽高尺寸不小于 300px；图片宽高比介于 1:2.5 ~ 2.5:1 之间。

Start/end frame image URL list with up to 2 images. Must be publicly accessible direct links. The first image is the start frame, and the second image is the end frame. Supported formats: .jpg / .jpeg / .png; max file size: 10MB; width and height must each be at least 300px; aspect ratio must be between 1:2.5 and 2.5:1.

最多 2 张：第 1 张为首帧，第 2 张为尾帧Up to 2 images: first = start frame, second = end frame
支持格式：Formats: .jpg .jpeg .png
单张 ≤ 10MBMax 10MB per image
宽高均 ≥ 300pxWidth and height each ≥ 300px
宽高比：1:2.5 ~ 2.5:1Aspect ratio: 1:2.5 ~ 2.5:1

input.durationstringoptionaldefault: 5

视频长度，单位：秒。

Video length in seconds.

510

input.aspect_ratiostringoptionaldefault: 16:9

生成视频帧的宽高比（宽:高）。

Generated video frame aspect ratio (width:height).

16:99:161:1

input.generate_audiobooleanoptional

自动生成音效

Auto-generate audio

callback_urlstring<uri>optional

HTTPS 回调地址

HTTPS callback URL

请求示例Request

              
              
            
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Img2Video",
    "model": "kling-v2-6",
    "mode": "pro",
    "callback_url": "",
    "input": {
      "prompt": "A conductor leads an orchestra joyfully",
      "images": ["https://example.com/frame.jpg"],
      "duration": "5",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'
            
import requests

res = requests.post(
    "https://models.storyclaw.com/v1/router/task/create",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "task": "Img2Video", "model": "kling-v2-6",
        "mode": "pro", "callback_url": "",
        "input": {
            "prompt": "A conductor leads an orchestra",
            "images": ["https://example.com/frame.jpg"],
            "duration": "5", "aspect_ratio": "16:9",
            "generate_audio": True,
        },
    }
)
print(res.json()["task_id"])
            

响应Response
200 OK
{ "code": 200, "message": "task created",
  "task_id": "Img2Video_kling-v2-6_207df23e..." }
            

Nano Banana 2 概览Nano Banana 2 Overview

Nano Banana 2（Gemini 3.1 Flash Image）是 Google DeepMind 推出的图像生成与编辑模型，在 Flash 速度下结合 Pro 级视觉质量、世界知识和更快的高级编辑能力。

Nano Banana 2 (Gemini 3.1 Flash Image) is Google DeepMind's image generation and editing model, combining Pro-level visual quality, world knowledge, and faster advanced editing at Flash speed.

🌐

接口地址Base URL

https://models.storyclaw.com

所有 Nano Banana 2 图像任务均通过此地址提交。

All Nano Banana 2 image tasks are submitted to this URL.

🔑

认证方式Authentication

Authorization: Bearer YOUR_API_KEY

与 Claude API 使用同一个 API Key。

Uses the same API Key as the Claude API.

⚙️

处理模式Processing Model

异步任务Async Task

提交任务后返回 task_id，通过查询接口轮询状态直到完成（status = 2）。结果链接有效期通常为 24 小时，请及时保存。

Submit a task to get a task_id, then poll the query endpoint until status = 2 (completed). Result URLs typically expire in 24 hours — save them promptly.

任务状态码Task Status Codes

0

排队中 — 任务已提交，等待调度Queued — submitted, waiting to be scheduled

1

处理中 — 模型正在生成图像Processing — model is generating the image

2

已完成 — 结果 URL 可用Completed — result URL is available

3

失败 — 请查看 error_msg 字段Failed — check the error_msg field

典型调用流程Typical Flow
# Step 1: 提交任务
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"model":"nano-banana-2","input":{...}}'

# Response → 获得 task_id
{ "code": 200, "task_id": "NanoBanana2_xxx" }

# Step 2: 轮询任务状态（每 3-5 秒一次）
curl --request GET \
  --url https://models.storyclaw.com/v1/router/tasks/NanoBanana2_xxx \
  --header 'Authorization: Bearer YOUR_API_KEY'

# status=2 时任务完成
{
  "status": 2,
  "results": [{ "urls": ["https://static.giggle.pro/.../image.png"] }]
}
            

文生图Text to Image

使用 Nano Banana 2 原生文生图能力，将自然语言提示词转成高质量图片，支持多种画幅比例、分辨率与输出格式。

Use Nano Banana 2's native text-to-image capability to turn natural-language prompts into high-quality images with multiple aspect ratios, resolutions, and output formats.

POST https://models.storyclaw.com/v1/router/task/create

Body application/json

taskstringrequired

固定传 Txt2Img

Always pass Txt2Img.

modelstringrequired

nano-banana-2

modestringrequired

固定传 fast

Always pass fast.

callback_urlstring<uri>optional

任务完成后的 HTTPS 回调地址，为空则需主动轮询。

HTTPS callback URL on completion. If empty, poll manually.

input.promptstringrequired

生成图片的提示词。

Prompt used to generate the image.

input.aspect_ratioenum<string>optionaldefault: auto

图片比例。

Image aspect ratio.

1:11:41:82:33:23:44:14:34:55:48:19:1616:921:9auto

input.resolutionenum<string>optionaldefault: 1K

图片分辨率。

Image resolution.

1K2K4K

input.output_formatenum<string>optionaldefault: jpg

图片输出格式。

Image output format.

pngjpg

响应（200 OK）Response (200 OK)

codeinteger

200 = 任务创建成功task created successfully

task_idstring

用于查询和取消任务。

Used to query or cancel the task.

请求示例Request

              
              
            
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Txt2Img",
    "model": "nano-banana-2",
    "mode": "fast",
    "callback_url": "https://example.com/results",
    "input": {
      "prompt": "A surreal painting of a giant banana floating in space, stars and galaxies in the background, vibrant colors, digital art",
      "aspect_ratio": "1:1",
      "resolution": "2K",
      "output_format": "jpg"
    }
  }'
            
import requests

res = requests.post(
    "https://models.storyclaw.com/v1/router/task/create",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "task": "Txt2Img",
        "model": "nano-banana-2",
        "mode": "fast",
        "callback_url": "https://example.com/results",
        "input": {
            "prompt": "A surreal painting of a giant banana floating in space",
            "aspect_ratio": "1:1",
            "resolution": "2K",
            "output_format": "jpg",
        },
    },
)
print(res.json()["task_id"])
            

响应Response
200 OK
{
  "code": 200,
  "message": "task created",
  "task_id": "Txt2Img_nano-banana-2_207df23e-6a1d-41b2-b7aa-ab0c535b1db0"
}
            

图生图Image to Image

使用 Nano Banana 2 图生图能力，基于输入图片和提示词进行转换或参考生成，支持最多 14 张参考图片。

Use Nano Banana 2's image-to-image capability to transform input images or use them as references with a prompt, supporting up to 14 reference images.

POST https://models.storyclaw.com/v1/router/task/create

Body application/json

taskstringrequired

固定传 Img2Img

Always pass Img2Img.

modelstringrequired

nano-banana-2

modestringrequired

固定传 fast

Always pass fast.

callback_urlstring<uri>optional

任务完成后的 HTTPS 回调地址，为空则需主动轮询。

HTTPS callback URL on completion. If empty, poll manually.

input.promptstringrequired

生成图片的提示词。

Prompt used to generate the image.

input.imagesarray[string<uri>]optional

用于转换或参考的输入图片 URL，最多 14 张。请传上传后的文件 URL，不传文件内容；支持 image/jpeg、image/png、image/webp，单张最大 30.0MB。

Input image URLs to transform or use as reference. Supports up to 14 images. Pass uploaded file URLs, not file content. Accepted types: image/jpeg, image/png, image/webp. Max size: 30.0MB per image.

<= 14 items

input.aspect_ratioenum<string>optionaldefault: auto

图片比例。

Image aspect ratio.

1:11:41:82:33:23:44:14:34:55:48:19:1616:921:9auto

input.resolutionenum<string>optionaldefault: 1K

图片分辨率。

Image resolution.

1K2K4K

input.output_formatenum<string>optionaldefault: jpg

图片输出格式。

Image output format.

pngjpg

响应（200 OK）Response (200 OK)

codeinteger

200 = 任务创建成功task created successfully

task_idstring

用于查询和取消任务。

Used to query or cancel the task.

请求示例Request

              
              
            
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Img2Img",
    "model": "nano-banana-2",
    "mode": "fast",
    "callback_url": "",
    "input": {
      "prompt": "Keep the model's pose and the flowing shape of the liquid dress unchanged. Change the clothing material from silver metal to completely transparent clear water (or glass). Through the liquid water, the model's skin details are visible. Lighting changes from reflection to refraction.",
      "images": [
        "https://static.giggle.pro/ipimg/airouter/20260205/Img2Img_nano-banana-pro_fba4791d-0668-4892-9fe0-3393454d5cc5/b6884e67c55c3a195fb3597b1a09963b.png"
      ],
      "resolution": "2K"
    }
  }'
            
import requests

res = requests.post(
    "https://models.storyclaw.com/v1/router/task/create",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "task": "Img2Img",
        "model": "nano-banana-2",
        "mode": "fast",
        "callback_url": "",
        "input": {
            "prompt": "Keep the model's pose and change the dress material to transparent clear water",
            "images": [
                "https://static.giggle.pro/ipimg/airouter/20260205/Img2Img_nano-banana-pro_fba4791d-0668-4892-9fe0-3393454d5cc5/b6884e67c55c3a195fb3597b1a09963b.png",
            ],
            "resolution": "2K",
        },
    },
)
print(res.json()["task_id"])
            

响应Response
200 OK
{
  "code": 200,
  "message": "task created",
  "task_id": "Img2Img_nano-banana-2_207df23e-6a1d-41b2-b7aa-ab0c535b1db0"
}
            

GPT Image 2 概览GPT Image 2 Overview

GPT Image 2 是 OpenAI 的先进图像生成模型，支持快速、高质量的图像生成与编辑，并可处理灵活尺寸和高保真的图像输入。

GPT Image 2 is OpenAI's state-of-the-art image generation model for fast, high-quality image generation and editing, with flexible image sizes and high-fidelity image inputs.

🌐

接口地址Base URL

https://models.storyclaw.com

所有 GPT Image 2 图像任务均通过此地址提交。

All GPT Image 2 image tasks are submitted to this URL.

🔑

认证方式Authentication

Authorization: Bearer YOUR_API_KEY

与 Claude API 使用同一个 API Key。

Uses the same API Key as the Claude API.

⚙️

处理模式Processing Model

异步任务Async Task

提交任务后返回 task_id，通过查询接口轮询状态直到完成（status = 2）。结果链接有效期通常为 24 小时，请及时保存。

Submit a task to get a task_id, then poll the query endpoint until status = 2 (completed). Result URLs typically expire in 24 hours — save them promptly.

任务状态码Task Status Codes

0

排队中 — 任务已提交，等待调度Queued — submitted, waiting to be scheduled

1

处理中 — 模型正在生成图像Processing — model is generating the image

2

已完成 — 结果 URL 可用Completed — result URL is available

3

失败 — 请查看 error_msg 字段Failed — check the error_msg field

典型调用流程Typical Flow
# Step 1: 提交任务
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"model":"gpt-image-2","input":{...}}'

# Response → 获得 task_id
{ "code": 200, "task_id": "GPTImage2_xxx" }

# Step 2: 轮询任务状态（每 3-5 秒一次）
curl --request GET \
  --url https://models.storyclaw.com/v1/router/tasks/GPTImage2_xxx \
  --header 'Authorization: Bearer YOUR_API_KEY'

# status=2 时任务完成
{
  "status": 2,
  "results": [{ "urls": ["https://static.giggle.pro/.../image.png"] }]
}
            

文生图Text to Image

使用 GPT Image 2 文生图能力，将自然语言提示词转成高质量图片，支持多种画幅比例与分辨率。

Use GPT Image 2's text-to-image capability to turn natural-language prompts into high-quality images with multiple aspect ratios and resolutions.

POST https://models.storyclaw.com/v1/router/task/create

Body application/json

taskstringrequired

固定传 Txt2Img

Always pass Txt2Img.

modelstringrequired

gpt-image-2-text-to-image

modestringrequired

固定传 fast

Always pass fast.

callback_urlstring<uri>optional

任务完成后的 HTTPS 回调地址，为空则需主动轮询。

HTTPS callback URL on completion. If empty, poll manually.

input.promptstringrequired

生成图片的提示词。

Prompt used to generate the image.

input.aspect_ratioenum<string>optionaldefault: auto

图片比例。

Image aspect ratio.

auto1:13:22:34:33:45:44:516:99:162:11:23:11:321:99:21

input.resolutionenum<string>optionaldefault: 1K

图片分辨率。

Image resolution.

1K2K4K

响应（200 OK）Response (200 OK)

codeinteger

200 = 任务创建成功task created successfully

task_idstring

用于查询和取消任务。

Used to query or cancel the task.

请求示例Request

              
              
            
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Txt2Img",
    "model": "gpt-image-2-text-to-image",
    "mode": "fast",
    "callback_url": "https://example.com/results",
    "input": {
      "prompt": "A surreal painting of a giant banana floating in space, stars and galaxies in the background, vibrant colors, digital art",
      "aspect_ratio": "auto",
      "resolution": "2K"
    }
  }'
            
import requests

res = requests.post(
    "https://models.storyclaw.com/v1/router/task/create",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "task": "Txt2Img",
        "model": "gpt-image-2-text-to-image",
        "mode": "fast",
        "callback_url": "https://example.com/results",
        "input": {
            "prompt": "A surreal painting of a giant banana floating in space",
            "aspect_ratio": "auto",
            "resolution": "2K",
        },
    },
)
print(res.json()["task_id"])
            

响应Response
200 OK
{
  "code": 200,
  "message": "task created",
  "task_id": "Txt2Img_gpt-image-2-text-to-image_207df23e-6a1d-41b2-b7aa-ab0c535b1db0"
}
            

图生图Image to Image

使用 GPT Image 2 图生图能力，基于输入图片 URL 和提示词生成或编辑图片，支持多种画幅比例与分辨率。

Use GPT Image 2's image-to-image capability to generate or edit images from input image URLs and a prompt, with multiple aspect ratios and resolutions.

POST https://models.storyclaw.com/v1/router/task/create

Body application/json

taskstringrequired

固定传 Img2Img

Always pass Img2Img.

modelstringrequired

gpt-image-2-image-to-image

modestringrequired

固定传 fast

Always pass fast.

callback_urlstring<uri>optional

任务完成后的 HTTPS 回调地址，为空则需主动轮询。

HTTPS callback URL on completion. If empty, poll manually.

input.promptstringrequired

生成图片的提示词。

Prompt used to generate the image.

input.imagesarray[string<uri>]optional

输入图片 URL 数组，最多 16 张。

Array of input image URLs.

<= 16 items

input.aspect_ratioenum<string>optionaldefault: auto

图片比例。

Image aspect ratio.

auto1:13:22:34:33:45:44:516:99:162:11:23:11:321:99:21

input.resolutionenum<string>optionaldefault: 1K

图片分辨率。

Image resolution.

1K2K4K

响应（200 OK）Response (200 OK)

codeinteger

200 = 任务创建成功task created successfully

task_idstring

用于查询和取消任务。

Used to query or cancel the task.

请求示例Request

              
              
            
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Img2Img",
    "model": "gpt-image-2-image-to-image",
    "mode": "fast",
    "callback_url": "https://example.com/results",
    "input": {
      "prompt": "A surreal painting of a giant banana floating in space, stars and galaxies in the background, vibrant colors, digital art",
      "images": ["https://example.com/input.png"],
      "aspect_ratio": "auto",
      "resolution": "2K"
    }
  }'
            
import requests

res = requests.post(
    "https://models.storyclaw.com/v1/router/task/create",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "task": "Img2Img",
        "model": "gpt-image-2-image-to-image",
        "mode": "fast",
        "callback_url": "https://example.com/results",
        "input": {
            "prompt": "A surreal painting of a giant banana floating in space",
            "images": ["https://example.com/input.png"],
            "aspect_ratio": "auto",
            "resolution": "2K",
        },
    },
)
print(res.json()["task_id"])
            

响应Response
200 OK
{
  "code": 200,
  "message": "task created",
  "task_id": "Img2Img_gpt-image-2-image-to-image_207df23e-6a1d-41b2-b7aa-ab0c535b1db0"
}
            

音乐生成Music Generation

使用 SUNO V5 生成带歌词或纯音乐的音频任务。接口采用异步任务模式，提交后返回 task_id，可通过查询接口轮询结果或配置回调接收通知。

Generate lyrical or instrumental music with SUNO V5. This is an async task endpoint: submit a task to receive a task_id, then poll for results or configure callbacks.

POST https://models.storyclaw.com/v1/router/task/create

Body application/json

taskstringrequired

固定传 Music

Always pass Music.

modelstringrequired

固定传 V5

Always pass V5.

modestringrequired

固定传 fast

Always pass fast.

callback_urlstring<uri>optional

StoryClaw 任务完成后的 HTTPS 回调地址，为空则需主动轮询。

StoryClaw HTTPS callback URL on task completion. If empty, poll manually.

input.promptstringconditional

音乐描述或歌词。customMode=false 时必填；customMode=true 且 instrumental=false 时必填；customMode=true 且 instrumental=true 时可选。V5 自定义模式最长 5000 字符，非自定义模式最长 500 字符。

Music description or lyrics. Required when customMode=false; required when customMode=true and instrumental=false; optional when customMode=true and instrumental=true. V5 custom mode supports up to 5000 characters; non-custom mode supports up to 500.

input.customModebooleanrequired

是否启用自定义模式。true 时按自定义模式校验 style、title、prompt 的条件必填；false 时仅 prompt 必填，其他自定义参数应留空。

Whether to enable custom mode. When true, style, title, and prompt follow custom-mode conditional requirements. When false, only prompt is required and other custom parameters should be empty.

input.instrumentalbooleanrequired

是否生成纯音乐。customMode=true 时，纯音乐需要 style 和 title；非纯音乐需要 style、prompt 和 title。

Whether to generate instrumental music. When customMode=true, instrumental tracks require style and title; non-instrumental tracks require style, prompt, and title.

input.pass_through.stylestringconditional

音乐风格。customMode=true 时必填；customMode=false 时应留空。V5 最长 1000 字符。

Music style. Required when customMode=true; should be empty when customMode=false. V5 maximum length: 1000 characters.

input.pass_through.titlestringconditional

歌曲标题。自定义模式必填，最长 80 字符。

Song title. Required in custom mode. Maximum length: 80 characters.

input.pass_through.negativeTagsstringoptional

不希望出现在音乐中的风格或元素，例如 Heavy Metal, Upbeat Drums。

Styles or elements to avoid, for example Heavy Metal, Upbeat Drums.

input.pass_through.vocalGenderenum<string>optional

期望的人声音色性别。

Preferred vocal gender.

mf

input.pass_through.styleWeightnumberoptional

风格遵循强度，示例使用 0.65。

Style adherence weight. The example uses 0.65.

input.pass_through.weirdnessConstraintnumberoptional

创意/怪异度约束，数值越高越可能产生更非常规的结果。

Creativity or weirdness constraint. Higher values may produce more unconventional results.

input.pass_through.audioWeightnumberoptional

音频参考权重，示例使用 0.65。

Audio reference weight. The example uses 0.65.

input.pass_through.callBackUrlstring<uri>required

SUNO 上游回调地址，固定传 https://api.example.com/callback。回调通常包含 text、first、complete 三个阶段。

Upstream SUNO callback URL. Always pass https://api.example.com/callback. Callbacks typically include text, first, and complete stages.

input.pass_through.personaIdstringoptional

已生成或保存的人格/风格 ID，用于复用特定音乐风格。

Saved persona or style ID used to reuse a specific musical style.

响应（200 OK）Response (200 OK)

codeinteger

200 = 任务创建成功task created successfully

task_idstring

用于查询和取消任务。

Used to query or cancel the task.

请求示例Request
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/create \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "task": "Music",
    "model": "V5",
    "mode": "fast",
    "callback_url": "",
    "input": {
      "prompt": "A calm and relaxing piano track with soft melodies",
      "customMode": true,
      "instrumental": true,
      "pass_through": {
        "title": "Peaceful Piano Meditation",
        "style": "Classical",
        "negativeTags": "Heavy Metal, Upbeat Drums",
        "vocalGender": "m",
        "styleWeight": 0.65,
        "weirdnessConstraint": 0.65,
        "audioWeight": 0.65,
        "callBackUrl": "https://api.example.com/callback",
        "personaId": "persona_123"
      }
    }
  }'
            

响应Response
200 OK
{
  "code": 200,
  "message": "task created",
  "task_id": "Music_V5_207df23e-6a1d-41b2-b7aa-ab0c535b1db0"
}
            

查询任务状态Query Task Status

通过 task_id 查询视频任务的当前状态和结果。建议轮询间隔 3–5 秒。

Query a video task's current status and result by task_id. Recommended polling interval: 3–5 seconds.

GEThttps://models.storyclaw.com/v1/router/tasks/{task_id}

路径参数Path Parameters

task_idstringrequired

创建任务时返回的 task_id，如 Txt2Video_seedance-2.0-pro_xxx

task_id returned on task creation, e.g. Txt2Video_seedance-2.0-pro_xxx

响应（200 OK）Response (200 OK)

task_idstring

任务 IDTask ID

statusinteger

0 排队1 处理中2 完成3 失败

results[].urlsstring[]

视频文件直链（status=2 时可用）

Video file URLs (available when status=2)

costinteger

本次任务消耗积分

Credits consumed

请求示例Request

              
              
            
curl --request GET \
  --url https://models.storyclaw.com/v1/router/tasks/Txt2Video_seedance-2.0-pro_207df23e \
  --header 'Authorization: Bearer YOUR_API_KEY'
            
import requests, time

task_id = "Txt2Video_seedance-2.0-pro_207df23e"
while True:
    r = requests.get(
        f"https://models.storyclaw.com/v1/router/tasks/{task_id}",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
    ).json()
    if r["status"] == 2:
        print("Done:", r["results"][0]["urls"]); break
    elif r["status"] == 3:
        print("Failed"); break
    time.sleep(5)
            

响应（已完成）Response (Completed)
200 OK
{
  "task_id": "Txt2Video_seedance-2.0-pro_207df23e",
  "status": 2,
  "results": [{
    "urls": ["https://static.giggle.pro/.../video.mp4"],
    "provider": "ark:global:seedance-2.0-pro"
  }],
  "cost": 80
}
            

取消任务Cancel Task

取消排队中（status=0）或处理中（status=1）的视频任务。

Cancel a queued (status=0) or processing (status=1) video task.

POSThttps://models.storyclaw.com/v1/router/task/stop

Body application/json

task_idstringrequired

要取消的任务 ID

The task_id to cancel

请求示例Request

              
            
curl --request POST \
  --url https://models.storyclaw.com/v1/router/task/stop \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"task_id":"Txt2Video_seedance-2.0-pro_207df23e"}'
            

响应Response
200 OK

              { "result": {"status":2,"message":"ok"}, "error": null }
            

回调说明Callback

创建任务时传入 callback_url，任务完成、失败或取消后服务器主动 POST 通知，无需轮询，适合生产环境。

Provide a callback_url when creating a task. The server will POST a notification on completion, failure, or cancellation — no polling needed.

安全规则Security Rules

x-authheader

服务器回调时在请求头中携带 x-auth: YOUR_API_KEY，请在回调接口中验证此值确认请求来源合法。

The server sends x-auth: YOUR_API_KEY in callback requests. Validate this header to verify the request origin.

约束Constraints

必须为 HTTPS，不支持 HTTPMust be HTTPS
禁止回调到内网地址（127.x、10.x、192.168.x 等）Internal IPs are blocked (127.x, 10.x, 192.168.x)
返回 2xx 视为成功，否则最多重试 3 次Return 2xx to acknowledge. Up to 3 retries on non-2xx

回调数据结构Callback Payload

task_idstring

statusinteger

2=完成completed, 3=失败failed

result.urlsstring[]

生成视频直链Generated video URLs

result.costinteger

消耗积分Credits consumed

error_msgstring

失败时的错误描述，成功时为空字符串Error description on failure, empty on success

回调数据示例Callback Payload
POST your-callback-url  ·  x-auth: YOUR_API_KEY
            
{
  "task_id": "Img2Video_seedance-2.0-pro_207df23e",
  "status": 2,
  "error_msg": "",
  "result": {
    "urls": ["https://static.giggle.pro/.../video.mp4"],
    "provider": "ark:global:seedance-2.0-pro",
    "cost": 60
  }
}
            

Python 处理示例Handler
from flask import Flask, request, jsonify

app = Flask(__name__)
MY_API_KEY = "YOUR_API_KEY"

@app.route("/callback", methods=["POST"])
def callback():
    # 验签
    if request.headers.get("x-auth") != MY_API_KEY:
        return jsonify({"error": "Unauthorized"}), 401
    data = request.json
    if data["status"] == 2:
        print("Video ready:", data["result"]["urls"])
    return jsonify({}), 200
            

错误码Error Codes

所有接口遵循标准 HTTP 状态码规范，请求失败时响应体包含具体错误信息。

All endpoints follow standard HTTP status codes. The response body includes error details on failure.

状态码Status	含义Meaning	说明Description
200	OK	请求成功Request succeeded
400	Bad Request	参数缺失或格式错误，检查请求 BodyMissing or malformed parameters. Check the request body
401	Unauthorized	API Key 无效或未传递，检查 Authorization 头Invalid or missing API Key. Check the Authorization header
402	Payment Required	账户积分不足，前往控制台充值Insufficient credits. Top up in the dashboard
403	Forbidden	无权访问该接口或资源Access denied to this endpoint or resource
429	Too Many Requests	请求频率超限，请稍后重试Rate limit exceeded. Retry later
500	Internal Server Error	服务器内部错误，稍后重试或联系支持Server error. Retry later or contact support

⚡

更多问题？联系我们Questions? Contact us

storyclaw.com →