Skip to content

快速开始 ​

使用免费的测试线路完成 创建任务 → 查询状态 → 读取结果。默认演示视频,也可以切换到图片示例。

本页使用原生 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 放入生成请求,素材类型和数量须满足所选模型能力。

已有兼容协议或 New API ​

两套接口的地址、字段和状态不同,见接口选择与通用约定。使用 New API 时按接入教程配置渠道。

星辰 AI · 图片与视频生成 API