Developer docs

Understand the API contract before you integrate.

A focused API surface for teams who want to move from idea to integrated experience without ceremony. Availability is always controlled by the live model catalog.

Star1Age-supported OpenAI-compatible subset

Star1Age API exposes a catalog-gated OpenAI-compatible surface for images, videos, chat, responses, audio, embeddings, and vision. It is not a complete or current official OpenAI API mirror: only models that pass the Star1Age model, pricing, credential, and release gates appear in /v1/models and accept requests.

Call /v1/models before sending a generation request. If its data array is empty, no public model is enabled yet and the generation examples below are illustrative only.

For machine-readable integration, fetch /v1/openapi.json. It is the source of truth for public endpoints, request fields, multipart forms, responses, and errors; provider names and upstream model names are internal and are not sent by clients.

1. Quickstart

First call /v1/models to confirm that a public model is enabled. If the catalog is empty, stop there and wait for a published model; otherwise create a production API key in Console, store it on your server, and use the v1 base URL. The request below is illustrative and uses the same Bearer authentication as the OpenAI-compatible endpoints.

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

OpenAI JavaScript SDK

Illustrative example: run this only after the model appears in /v1/models. The OpenAI JavaScript client can target Star1Age with a custom baseURL. Keep the API key in a server-side environment variable. This SDK example covers the Images endpoint; videos use Star1Age’s legacy Videos-compatible multipart job contract documented below.

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

Illustrative example: run this only after the model appears in /v1/models. The OpenAI Python client accepts base_url for the Star1Age Images endpoint. Keep the key outside source control. Video creation remains Star1Age’s legacy Videos-compatible multipart job contract described in the Videos section.

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. Authentication and scopes

Send a production key as Authorization: Bearer sa_live_.... Keys are shown once when created or rotated. Assign only the scopes your integration needs; the server rejects requests that lack the required scope. A scope can exist before a matching model is released; model availability is always determined by /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. Images

Illustrative request: first confirm the model is listed by /v1/models. POST /v1/images/generations creates an image synchronously. The public contract keeps the OpenAI-compatible body and preserves provider detail fields: model, prompt, size, quality, n (1-4), response_format, negative_prompt, seed, watermark, prompt_extend, enable_interleave, and an optional parameters object. Explicit sizes such as 1280*720 are passed through; clients do not send provider or upstream model names. Fetch /v1/openapi.json for the current machine-readable schema.

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. Videos

Illustrative request: submit it only when the selected model appears in /v1/models. Star1Age exposes a Videos-compatible asynchronous job contract at POST /v1/videos using multipart/form-data. Poll the returned video id with GET /v1/videos/:id until it is completed, then use /content to retrieve the current content redirect. Model IDs, resolution, aspect ratio, duration, native parameters, accepted references, and active prices are defined by the public model catalog. HappyHorse 1.0 exposes its complete 720P/1080P, 3-15 second, nine-ratio, watermark, and seed contract. Video list results use after, limit, and order cursors.

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. Errors

Errors use a structured object with message, type, param, and code. Treat 4xx responses as request or authorization problems; 5xx responses may represent a provider or temporary service failure. Preserve the x-request-id response header for support and tracing.

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

6. Rate limits

The API applies both API-key and IP dimensions. Read the returned headers instead of hard-coding a retry interval. When a limit is exceeded, the response is 429 and Retry-After contains the server-provided delay in seconds.

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

Idempotency-Key is a Star1Age extension supported by generation endpoints. Send a client-generated key when a request may be retried. The same key with the same API key, endpoint, and payload reuses the original result for 24 hours. Reusing a key with a different payload returns a conflict instead of creating a second job.

Idempotency-Key: checkout-image-20260816-001

8. Text streaming

Catalog-enabled text models support resumable SSE on both POST /v1/chat/completions and POST /v1/responses. Always reuse the same Idempotency-Key when reconnecting, and send the last received SSE id as Last-Event-ID to continue from the next frame. Omitting Last-Event-ID replays the stream from the beginning. Closing the client connection does not cancel provider execution: the request continues in the background, the encrypted terminal result is retained for replay, and normal usage-based billing still applies.

# 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

The interactive reference below is rendered directly from /v1/openapi.json, the single source of truth for the public contract.

Loading API Reference · 正在载入 API Reference…