---
name: sichang-api
description: 用思畅 AI 开发者 API 生成图片与视频。需要用户提供 API Key(sc_ 开头)。
---

# 思畅 AI 开发者 API

Base URL `https://sichang.xyz/api/v1`,全部 JSON。每个请求带 `Authorization: Bearer <API Key>`。
key 由用户在 https://sichang.xyz/settings?tab=api 创建,只在创建时展示一次;不要把它写进代码仓库或日志。
使用 API 须遵守 https://sichang.xyz/developers/terms(禁止转售与代生成、产物内容责任归用户)。完整字段定义见 https://sichang.xyz/developers/openapi.yaml 。

## 先自检

```bash
curl -s https://sichang.xyz/api/v1/me -H "Authorization: Bearer $SICHANG_API_KEY"
```

返回余额(`credits` + `subscriptionCredits`)、这把 key 的 `scopes`(`image` / `video`)与限额。没有对应 scope 就不要调那个端点。

## 看模型

```bash
curl -s "https://sichang.xyz/api/v1/models?type=image" -H "Authorization: Bearer $SICHANG_API_KEY"
curl -s "https://sichang.xyz/api/v1/models?type=video" -H "Authorization: Bearer $SICHANG_API_KEY"
```

图片目录里 `kind: generate` 的模型用于文生图,`kind: edit` 的用于改图;`creditCost` 是每张积分。
视频目录里 `mode` 决定要不要传首帧(`image-to-video`)、参考图(`reference-to-video`)或源视频(`video-extend` / `video-edit`),`durations` / `resolutions` / `aspectRatios` 是可选值。

## 生成图片(异步)

```bash
curl -s -X POST https://sichang.xyz/api/v1/images \
  -H "Authorization: Bearer $SICHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt":"a corgi surfing at sunset","model":"z-image-turbo","aspectRatio":"16:9","resolution":"1K"}'
```

返回 `202 { "job": { "id": "...", "status": "PROCESSING", ... } }`。改图:先上传(见下),再把 `inputs: [{ "key": "<上传返回的 key>" }]` 加进请求体,`model` 换成 `kind: edit` 的模型。

## 生成视频(异步)

```bash
curl -s -X POST https://sichang.xyz/api/v1/videos \
  -H "Authorization: Bearer $SICHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt":"a corgi surfing at sunset","model":"<video model id>","duration":"5","resolution":"720p","aspectRatio":"16:9"}'
```

首帧用 `imageKey`,参考图用 `referenceImageKeys`,源视频用 `videoKey` 或 `sourceJobId`(你之前的视频 job id)。

## 轮询直到完成

```bash
curl -s "https://sichang.xyz/api/v1/jobs/$JOB_ID?wait=30" -H "Authorization: Bearer $SICHANG_API_KEY"
```

`wait=30` 让服务器最多等 30 秒再返回;`status` 不是 `COMPLETED` / `FAILED` / `EXPIRED` 就再调一次。图片通常 10–90 秒,视频 1–10 分钟。
完成后 `outputs[0].url`(查看)与 `outputs[0].downloadUrl`(下载)**15 分钟后失效,拿到就下载,不要保存 URL**;之后要再取,重新 GET 一次 job 即可。
`FAILED` 的任务已自动退款(`credits.refunded`),`error.code` 说明原因。

## 上传素材(两步)

```bash
# 1. 拿预签名 URL(target=image 用于改图输入,target=video 用于视频素材;size 必须等于文件字节数)
curl -s -X POST https://sichang.xyz/api/v1/uploads \
  -H "Authorization: Bearer $SICHANG_API_KEY" -H "Content-Type: application/json" \
  -d "{\"kind\":\"image\",\"target\":\"video\",\"contentType\":\"image/png\",\"size\":$(stat -c%s in.png)}"
# 2. 直接 PUT 到 uploadUrl(Content-Type 必须与第 1 步一致)
curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @in.png
```

之后把第 1 步返回的 `key` 填进 `inputs` / `imageKey` 等字段。素材有效期见 `expiresAt`。

## 列出任务

```bash
curl -s "https://sichang.xyz/api/v1/jobs?type=image&limit=20" -H "Authorization: Bearer $SICHANG_API_KEY"
```

含网页端提交的任务,`origin` 区分;翻页用返回的 `nextCursor`。

## 错误处理

所有错误都是 `{ "error": { "code", "message", "details"? } }`:

| HTTP | code | 怎么办 |
|---|---|---|
| 400 | `VALIDATION_ERROR` | 看 `details.field` 改请求;`details.allowed` 列出可选值 |
| 401 | `UNAUTHENTICATED` | key 无效 / 吊销 / 过期,让用户重新创建 |
| 402 | `CREDITS_EXHAUSTED` | 积分不足,提示用户到 https://sichang.xyz/pricing 充值;`details.required` 是本次需要的积分 |
| 403 | `SCOPE_DENIED` / `API_NOT_ELIGIBLE` / `API_DISABLED` / `ACCOUNT_SUSPENDED` | key 没这个权限 / 账号未达准入 / API 未开放 / 账号停用;都不是重试能解决的 |
| 409 | `IDEMPOTENCY_*` | 同一个 `Idempotency-Key` 已经用过:换新 key,或按 `IDEMPOTENCY_IN_FLIGHT` 稍后查询 |
| 422 | `CONTENT_VIOLATION` | 提示词被内容审核拦下,**不要原样重试**,改写描述 |
| 429 | `RATE_LIMITED` / `CONCURRENCY_LIMIT` / `DAILY_CAP_REACHED` | 按响应头 `Retry-After`(秒)等待;`X-RateLimit-Remaining` 告诉你还剩多少 |
| 503 | `MODERATION_UNAVAILABLE` / `UPSTREAM_UNAVAILABLE` | 未扣费或已退费,稍后重试一次 |

每次提交都带一个新的 `Idempotency-Key`(UUID);网络超时后用**同一个** key 重发,会拿回同一个 job 而不会重复扣费。

## 积分

与网页同价、无附加费:图片按模型每张计,视频按模型 × 时长 × 分辨率计,提交时扣、失败自动退。
每把 key 每天最多用 20,000 积分(创建时可调低),每分钟最多 10 次提交,在途任务图片 10 / 视频 5。