主题
快速开始
使用免费的测试线路完成 创建任务 → 查询状态 → 读取结果。默认演示视频,也可以切换到图片示例。
本页使用原生 OpenAPI,Base URL 为 https://api.video.aistarslab.com/openapi。兼容平台接入见 OpenAI 兼容接口。
测试会得到什么?
测试线路不扣生成积分,不真实生成内容。创建后查询会直接返回成功和固定测试输出,用于验证接入流程;正式模型需要异步等待。测试线路说明
1. 准备 API Key
在官网创建 API Key,设置环境变量。cURL 使用 Bash 语法;Windows 可用 Git Bash,或运行本页末尾的 Python 示例。
bash
export AISTARSLAB_API_KEY='YOUR_API_KEY'powershell
$env:AISTARSLAB_API_KEY = 'YOUR_API_KEY'真实 Key 只保存在自己的服务端或本地环境,不写入公开网页或代码仓库。
2. 创建测试任务
bash
curl 'https://api.video.aistarslab.com/openapi/generation/create/video' \
-H "Authorization: Bearer $AISTARSLAB_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"channel": "test",
"model": "test-video",
"prompt": "海边日落,镜头缓慢向前推进",
"aspectRatio": "16:9",
"quality": "720p",
"duration": 5,
"mode": "text2video"
}'bash
curl 'https://api.video.aistarslab.com/openapi/generation/create/image' \
-H "Authorization: Bearer $AISTARSLAB_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"channel": "test",
"model": "test-image",
"prompt": "一只白色陶瓷杯,柔和自然光",
"aspectRatio": "1:1",
"quality": "1K",
"n": 1
}'视频创建响应示例:
json
{
"code": 0,
"msg": "success",
"data": {
"taskId": "test_video_example",
"type": 2,
"status": 2,
"costCredits": 0
}
}检查 HTTP 状态及 code=0,保存实际返回的 data.taskId。status=2 表示已受理并执行中。图片任务的 type 为 1,任务 ID 以 test_image_ 开头。
3. 查询状态和结果
将 YOUR_TASK_ID 替换为刚创建的任务 ID,两种任务使用同一个查询接口。
bash
curl --get 'https://api.video.aistarslab.com/openapi/generation/status' \
-H "Authorization: Bearer $AISTARSLAB_API_KEY" \
--data-urlencode 'taskId=YOUR_TASK_ID'json
{
"code": 0,
"msg": "success",
"data": {
"taskId": "test_video_example",
"type": 2,
"status": 3,
"progress": 100,
"outputs": ["https://example.com/test-result.mp4"]
}
}这里的 ID 和输出 URL 仅示意字段位置,请使用实际响应。data.status=3 表示成功,data.outputs 是结果 URL 数组。 测试结果为固定内容,不能用来判断模型实际生成质量。
真实任务的状态为:1 等待、2 执行中、3 成功、4 失败。建议每 10~15 秒查询一次,进入终态后停止;多个任务优先批量查询。
遇到错误时
code != 0 表示请求失败;code=0 但 data.status=4 表示查询成功、任务执行失败,应读取 errorCode 和 errorMessage。创建请求超时不要直接自动重试。详见错误处理与轮询。
4. 切换到真实模型
bash
curl 'https://api.video.aistarslab.com/openapi/generation/config' \
-H "Authorization: Bearer $AISTARSLAB_API_KEY"从响应的 data.videoConfig 或 data.imageConfig 选择同一线路下的模型及能力,替换测试请求中的参数。视频需要选择支持的时长和模式,图片需要选择支持的数量;不要照抄文档中的示例模型 ID。
真实任务会扣减积分。详见模型配置、创建图片、创建视频和计费与退款。
Python 完整示例
仅依赖 Python 3 标准库。设置上述环境变量后,把以下代码保存为 quickstart.py,运行 python quickstart.py 测试视频,或 python quickstart.py image 测试图片。
该示例最多查询 60 次,每次请求超时 30 秒,查询间隔 12 秒;创建请求只发一次。停止本地等待不会取消服务端任务。
py
"""免费测试线路示例:python examples/quickstart.py [video|image]。"""
import argparse
import json
import os
import time
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen
BASE_URL = "https://api.video.aistarslab.com/openapi"
MAX_POLLS = 60
POLL_INTERVAL = 12
def request_api(path, api_key, body=None):
request = Request(
BASE_URL + path,
data=None if body is None else json.dumps(body).encode("utf-8"),
headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
method="GET" if body is None else "POST",
)
with urlopen(request, timeout=30) as response:
result = json.loads(response.read().decode("utf-8"))
if result.get("code") != 0:
raise RuntimeError(f"请求失败:code={result.get('code')},{result.get('msg')}")
return result["data"]
def run(kind, api_key):
body = {"channel": "test", "model": f"test-{kind}", "prompt": "海边日落,柔和自然光",
"aspectRatio": "16:9", "quality": "1K" if kind == "image" else "720p"}
body.update({"n": 1} if kind == "image" else {"duration": 5, "mode": "text2video"})
# 创建请求仅提交一次,网络超时不自动重试,避免重复创建真实任务。
created = request_api(f"/generation/create/{kind}", api_key, body)
task_id = created["taskId"]
print(f"任务 ID:{task_id},请保存,后续均查询此任务。", flush=True)
for attempt in range(MAX_POLLS):
if attempt:
time.sleep(POLL_INTERVAL)
try:
task = request_api("/generation/status?" + urlencode({"taskId": task_id}), api_key)
except HTTPError as error:
if 500 <= error.code < 600:
continue # 仅查询请求允许对暂时性服务异常进行有限重试。
raise
except (URLError, TimeoutError):
continue
if task["status"] == 3:
outputs = task.get("outputs") or []
if not outputs:
raise RuntimeError(f"任务 {task_id} 已成功但未返回输出,请保留 ID 核查。")
for url in outputs:
print(url)
return outputs
if task["status"] == 4:
raise RuntimeError(f"任务失败:{task.get('errorCode')},{task.get('errorMessage')}")
if task["status"] not in (1, 2):
raise RuntimeError(f"未知任务状态:{task['status']},任务 ID:{task_id}")
raise TimeoutError(f"已停止轮询,任务未取消。稍后可继续查询:{task_id}")
if __name__ == "__main__":
parser = argparse.ArgumentParser(description="星辰 AI 免费测试线路")
parser.add_argument("kind", choices=["video", "image"], nargs="?", default="video")
args = parser.parse_args()
api_key = os.environ.get("AISTARSLAB_API_KEY")
if not api_key:
parser.error("请先设置环境变量 AISTARSLAB_API_KEY")
try:
run(args.kind, api_key)
except HTTPError as error:
if error.code == 429:
raise SystemExit(f"请求受限,请检查 Key,并按 Retry-After 等待:{error.headers.get('Retry-After', '未提供')} 秒。")
raise SystemExit(f"HTTP {error.code}:请按错误处理文档排查。")
except (URLError, TimeoutError, RuntimeError) as error:
raise SystemExit(f"{error}\n若创建阶段未收到任务 ID,请先核实任务记录,不要直接重复创建。")使用参考素材
生成请求接收公网可访问的 HTTP/HTTPS 素材 URL。本地文件可先通过素材上传接口上传,再将 URL 放入生成请求,素材类型和数量须满足所选模型能力。