SStar1Age API

开发者文档

接入前先了解 API 契约。

为希望快速从想法进入产品集成的团队提供专注、清晰的 API。实际可用性始终由实时模型目录控制。

Star1Age 支持的 OpenAI-compatible 子集

Star1Age API 提供由模型目录控制的 OpenAI-compatible 接口，覆盖图像、视频、chat、responses、音频、embeddings 与 vision。它不是完整或现行的官方 OpenAI API 镜像；只有通过 Star1Age 模型、计价、凭证与发布门禁的模型，才会出现在 /v1/models 并接受请求。

发送生成请求前请先调用 /v1/models。如果 data 数组为空，表示目前尚未启用公开模型，下面的生成示例仅用于说明请求格式。

如果由 SDK 或 Agent 自动接入，请读取 /v1/openapi.json。它是公开端点、请求字段、multipart 表单、响应与错误格式的唯一机器可读来源；Provider 名称与上游模型名称属于内部信息，客户端不需要传送。

1. 快速开始

请先调用 /v1/models，确认已有公开模型启用。如果目录为空，请先停在这里并等待模型发布；否则再在控制台创建生产 API Key，将它保存在服务端，并使用 v1 基础地址。下面的请求仅用于说明格式，使用与 OpenAI-compatible 端点相同的 Bearer 鉴权方式。

curl https://api.star1age.cn/v1/models \
  -H "Authorization: Bearer $STAR1AGE_API_KEY"

OpenAI JavaScript SDK

示例代码：只有模型出现在 /v1/models 后才可以执行。OpenAI JavaScript 客户端可以通过自定义 baseURL 指向 Star1Age。请将 API Key 保存在服务端环境变量中。此 SDK 示例覆盖 Images endpoint；视频使用下方说明的 Star1Age legacy Videos-compatible multipart job contract。

npm install openai

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.STAR1AGE_API_KEY,
  baseURL: 'https://api.star1age.cn/v1'
});

const result = await client.images.generate({
  model: 'star1age-wan2.7-image-pro',
  prompt: 'A cinematic city at dusk',
  size: '1280*720',
  n: 1,
  watermark: false,
  response_format: 'url'
});

console.log(result.data[0]?.url);

OpenAI Python SDK

示例代码：只有模型出现在 /v1/models 后才可以执行。OpenAI Python 客户端可以使用 base_url 调用 Star1Age Images endpoint。请勿把 Key 提交到源代码管理。视频创建仍使用“视频”章节描述的 Star1Age legacy Videos-compatible multipart job contract。

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["STAR1AGE_API_KEY"],
    base_url="https://api.star1age.cn/v1",
)

result = client.images.generate(
    model="star1age-wan2.7-image-pro",
    prompt="A cinematic city at dusk",
    size="1280*720",
    n=1,
    watermark=False,
    response_format="url",
)

print(result.data[0].url)

2. 鉴权与权限

生产环境使用 Authorization: Bearer sa_live_... 发送 Key。Key 只会在创建或轮换成功时完整显示一次。请只授予应用所需权限；缺少对应权限时，服务端会拒绝请求。某个权限可以先于对应模型存在；实际可用模型始终以 /v1/models 为准。

Authorization: Bearer sa_live_...

Available scopes:
  models:read
  chat:generate
  responses:generate
  images:generate
  images:edit
  videos:generate
  videos:read
  audio:speech
  audio:transcribe
  embeddings:create
  vision:analyze

3. 图像

示例请求：请先确认模型已列在 /v1/models。POST /v1/images/generations 同步创建图像。公开契约保持 OpenAI-compatible body，并保留 Provider 细节参数：model、prompt、size、quality、n（1-4）、response_format、negative_prompt、seed、watermark、prompt_extend、enable_interleave，以及可选的 parameters 对象。像 1280*720 这样的明确尺寸会原样传递；客户端不需要传 provider 或上游模型名称。当前机器可读 schema 请读取 /v1/openapi.json。

curl https://api.star1age.cn/v1/images/generations \
  -H "Authorization: Bearer $STAR1AGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-demo-001" \
  -d '{
    "model": "star1age-wan2.7-image-pro",
    "prompt": "A cinematic city at dusk",
    "size": "1280*720",
    "n": 1,
    "watermark": false,
    "response_format": "url"
  }'

4. 视频

示例请求：只有选中的模型出现在 /v1/models 后才可以提交。Star1Age 在 POST /v1/videos 提供异步 Videos-compatible multipart/form-data 任务接口。创建后使用返回的 video id 调用 GET /v1/videos/:id 轮询，直到状态为 completed，再通过 /content 获取当前内容跳转地址。模型 ID、分辨率、画幅、时长、原生参数、可接受的参考素材与当前价格均以公开模型目录为准。HappyHorse 1.0 对外提供完整的 720P/1080P、3～15 秒、九种画幅、watermark 与 seed contract。视频列表支持 after、limit 与 order 游标参数。

curl https://api.star1age.cn/v1/videos \
  -X POST \
  -H "Authorization: Bearer $STAR1AGE_API_KEY" \
  -H "Idempotency-Key: video-demo-001" \
  -F "model=star1age-happyhorse-1.0" \
  -F "prompt=A slow aerial shot over a neon-lit city at night." \
  -F "seconds=5" \
  -F "size=1280x720"

curl https://api.star1age.cn/v1/videos/video_request_id \
  -H "Authorization: Bearer $STAR1AGE_API_KEY"

curl -L https://api.star1age.cn/v1/videos/video_request_id/content \
  -H "Authorization: Bearer $STAR1AGE_API_KEY" \
  -o output.mp4

5. 错误处理

错误使用包含 message、type、param 与 code 的结构化对象。4xx 通常表示请求或权限问题；5xx 可能表示 Provider 或临时服务故障。请保留响应中的 x-request-id Header，便于排查与支持。

{
  "error": {
    "message": "Rate limit exceeded.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

6. 速率限制

API 同时按 API Key 与 IP 维度限流。请读取响应 Header，不要把重试间隔写死。超过限制时返回 429，Retry-After 会提供服务端建议等待秒数。

x-ratelimit-limit-key: <current-key-limit>
x-ratelimit-remaining-key: <remaining-key-requests>
x-ratelimit-limit-ip: <current-ip-limit>
x-ratelimit-remaining-ip: <remaining-ip-requests>
retry-after: <seconds>

7. 幂等请求

Idempotency-Key 是 Star1Age 为生成接口提供的扩展能力。客户端可能重试时，请发送自行生成的 Key。同一 API Key、端点和 payload 在 24 小时内使用相同 Key 会复用原结果；相同 Key 配合不同 payload 会返回冲突，不会建立第二个任务。

Idempotency-Key: checkout-image-20260816-001

8. 文字串流

目录中已启用串流能力的文字模型，可在 POST /v1/chat/completions 与 POST /v1/responses 使用可续传 SSE。重新连接时必须沿用同一个 Idempotency-Key，并将最后收到的 SSE id 放入 Last-Event-ID，服务端会从下一帧继续；不传 Last-Event-ID 则会从头重播。客户端关闭连接不会取消 Provider 执行：请求会在后台继续，完整加密结果会保留供重播，并照常依实际 usage 计费。

# Chat Completions SSE
curl -N https://api.star1age.cn/v1/chat/completions \
  -H "Authorization: Bearer $STAR1AGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-stream-demo-001" \
  -d '{
    "model": "star1age-gpt-5.5",
    "messages": [{"role": "user", "content": "Reply with one short sentence."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

# Responses SSE (bridged to the verified chat-completions upstream)
curl -N https://api.star1age.cn/v1/responses \
  -H "Authorization: Bearer $STAR1AGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: responses-stream-demo-001" \
  -d '{
    "model": "star1age-gpt-5.5",
    "instructions": "Be concise.",
    "input": "Reply with one short sentence.",
    "stream": true
  }'

# Resume after disconnect using the same request identity
curl -N https://api.star1age.cn/v1/chat/completions \
  -H "Authorization: Bearer $STAR1AGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-stream-demo-001" \
  -H "Last-Event-ID: <last-sse-id>" \
  -d '{
    "model": "star1age-gpt-5.5",
    "messages": [{"role": "user", "content": "Reply with one short sentence."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

9. API Reference

下方互动式 Reference 直接读取 /v1/openapi.json，这是公开 API 契约的唯一来源。

Loading API Reference · 正在载入 API Reference…
开发者文档 | Star1Age API