Opencran API: 在你自己的代码中调用每个模型

1 · 身份验证

在设置的 API 密钥中创建密钥。每次请求都以 Bearer 令牌的形式发送。密钥以 oc_live_ 开头,仅在 Opencran 上有效;请将其保存在你的服务器上,切勿放在浏览器或应用中。

curl

curl https://opencran.com/api/v1/api/catalog/me \
  -H 'Authorization: Bearer oc_live_...'

2 · 选择模型

选择一个模型,即可查看根据其自身字段生成的现成请求。必填字段已填好,所有可选设置都使用模型的默认值。

已选模型opencran/fast-image/text-to-image

模型页面 →

字段
名称	类型	必填	默认值
prompt	text	是	-
aspect_ratio	1:1 \| 2:1 \| 1:2 \| 3:1 \| 1:3 \| 21:9 \| ...	否	1:1

3 · 开始生成

一次调用即可按你的具体输入计算价格并从余额中扣费。响应会立即返回,状态为 queued,生成在后台进行。请发送 Idempotency-Key 请求头,这样重试的请求永远不会重复扣费。

curl

curl -X POST https://opencran.com/api/v1/api/catalog/generations \
  -H 'Authorization: Bearer oc_live_...' \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "modelId": "opencran/fast-image/text-to-image",
  "inputs": {
    "prompt": "a lighthouse on a cliff at dusk, soft light"
  }
}'

先查询价格 (可选)

使用相同的输入计算价格,但不会启动任何生成。结果以分为单位。

curl

curl -X POST https://opencran.com/api/v1/api/catalog/quote \
  -H 'Authorization: Bearer oc_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"modelId":"opencran/fast-image/text-to-image","inputs":{"prompt":"a lighthouse on a cliff at dusk, soft light"}}'

4 · 轮询并下载

每隔几秒查询一次生成状态,直到状态变为 succeeded、failed 或 refunded。成功后,使用同一密钥从 contentUrl 下载文件。文本模型则会在 textOutput 中返回回答。

curl

curl https://opencran.com/api/v1/api/catalog/generations/GENERATION_ID \
  -H 'Authorization: Bearer oc_live_...'

curl

curl https://opencran.com/api/v1/api/catalog/generations/GENERATION_ID/content \
  -H 'Authorization: Bearer oc_live_...' \
  -o result.png

接口

基础 URL: https://opencran.com/api/v1/api/catalog

GET	/me	你的密钥和余额
GET	/models	所有模型
GET	/models/detail?id=MODEL_ID	单个模型及其字段
POST	/quote	指定输入的价格
POST	/generations	开始生成
GET	/generations	你最近的生成
GET	/generations/ID	单个生成的状态
GET	/generations/ID/content	结果文件
DELETE	/generations/ID	删除生成

价格与余额

通过 API 生成与工作室使用同一余额,价格也相同。API 中的所有金额均以欧分计: costCents 是一次生成扣除的金额,balanceCents 是剩余余额。

错误与限制

错误以包含代码和消息的 JSON 返回。401：密钥缺失、错误或已撤销。400：某个字段无效（详情会指明）。402：余额不足。429：请求过多，请放慢速度。失败的渲染会自动退款。确切限额将在密钥推出时公布。返回 HTML 页面的 403:请求在到达 API 之前被拦截,通常是因为 User-Agent。Python-urllib 的默认值会被拦截,请自行设置,例如 User-Agent: my-app/1.0。