OpenAI 兼容 API

KoCodeImg 接口文档

使用一个 API Key 调用图片和视频生成能力。接口遵循 OpenAI SDK 的常用调用方式，当前公开支持模型查询、图片生成、图片编辑、素材上传和异步视频任务。

基础地址https://koimg.com/v1

认证方式Authorization: Bearer sk-koci_...

方法	路径	用途
GET	/models	查询模型
POST	/images/generations	生成图片
POST	/images/edits	编辑图片
POST	/uploads	上传素材
POST	/videos	提交视频任务
GET	/videos/{id}	查询视频任务
DELETE	/videos/{id}	删除视频记录

快速开始

1
创建 API Key
登录后前往账号设置，在“API 密钥”区域创建密钥。完整密钥只在创建时显示一次。
2
保存到环境变量
不要把密钥写进前端代码、移动应用或 Git 仓库。
3
查询模型并发送请求
模型由管理员动态配置，调用前通过 GET /models 获取当前可用模型。

bash

export KOCODEIMG_API_KEY="sk-koci_your_api_key"

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KOCODEIMG_API_KEY"],
    base_url="https://koimg.com/v1",
    timeout=600.0,
)

models = client.models.list()
print([(model.id, getattr(model, "kind", None)) for model in models.data])

认证

所有 /v1 接口仅接受 Bearer API Key。网站登录使用的 JWT、X-API-Key 请求头和 URL 查询参数均不能代替 API Key。

Authorization: Bearer $KOCODEIMG_API_KEY

API Key 与用户账号绑定，图片和视频消耗该账号积分，并受密钥的每日、每月配额限制。

查询可用模型

返回当前启用的图片和视频模型。请根据响应中的 kind 选择对应接口，不要依赖文档中写死的模型名称。

GEThttps://koimg.com/v1/models

bash

curl https://koimg.com/v1/models \
  -H "Authorization: Bearer $KOCODEIMG_API_KEY"

json

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "model",
      "owned_by": "kocodeimg",
      "kind": "image"
    },
    {
      "id": "sora-2",
      "object": "model",
      "owned_by": "kocodeimg",
      "kind": "video"
    }
  ]
}

图片生成

同步生成图片。请求会等待生成完成并返回 URL 或 Base64，建议客户端超时设置为 10 分钟。

POSThttps://koimg.com/v1/images/generations

请求参数

参数名	类型	必填	说明
model	`string`	否	图片模型 ID；默认 gpt-image-2，建议先查询 /models
prompt	`string`	是	图片描述，最多 32,000 字符
n	`integer`	否	数量，接口接受 1-10，当前单次最多实际生成 4 张
size	`string`	否	默认 1024x1024；支持像素尺寸、1:1/16:9/9:16/4:3/3:4 或 auto
quality	`string`	否	low/medium/high/auto、standard/hd 或 1k/2k/4k
response_format	`string`	否	url（默认）或 b64_json
style	`string`	否	兼容 vivid/natural；是否生效取决于模型
background	`string`	否	transparent、opaque 或 auto；是否生效取决于模型
output_format	`string`	否	png、jpeg 或 webp；默认 webp
output_compression	`integer`	否	0-100；是否生效取决于输出格式和模型
moderation	`string`	否	low 或 auto
reference_images	`string[]`	否	非 OpenAI 扩展；仅接受 /uploads 返回的本站 URL

bash

curl https://koimg.com/v1/images/generations \
  -H "Authorization: Bearer $KOCODEIMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "清晨薄雾中的山间湖泊，电影感自然光",
    "n": 1,
    "size": "16:9",
    "quality": "2k",
    "response_format": "url",
    "output_format": "webp"
  }'

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KOCODEIMG_API_KEY"],
    base_url="https://koimg.com/v1",
    timeout=600.0,
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="清晨薄雾中的山间湖泊，电影感自然光",
    n=1,
    size="1024x1024",
    quality="high",
    response_format="url",
)
print(result.data[0].url)

图片编辑与图生图

使用 multipart/form-data 上传一张或多张参考图。每张图片不能超过 10MB，并会进行内容审核。当前接口会忽略 mask 文件，不提供像素级遮罩重绘保证。

POSThttps://koimg.com/v1/images/edits

表单字段

参数名	类型	必填	说明
image	`file`	是	参考图；多图可重复 image 字段，或使用 image[]、image_2 等名称
prompt	`string`	是	期望的修改效果
model	`string`	否	图片模型 ID；默认 gpt-image-2
n	`integer`	否	输出数量，当前最多 4 张
size	`string`	否	像素尺寸或宽高比
quality	`string`	否	与图片生成接口一致
response_format	`string`	否	url 或 b64_json
output_format	`string`	否	png、jpeg 或 webp

bash

curl https://koimg.com/v1/images/edits \
  -H "Authorization: Bearer $KOCODEIMG_API_KEY" \
  -F "image=@reference.png" \
  -F "prompt=保留主体构图，将背景改为夜晚城市" \
  -F "model=gpt-image-2" \
  -F "size=1:1" \
  -F "quality=2k"

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KOCODEIMG_API_KEY"],
    base_url="https://koimg.com/v1",
    timeout=600.0,
)

with open("reference.png", "rb") as image:
    result = client.images.edit(
        model="gpt-image-2",
        image=image,
        prompt="保留主体构图，将背景改为夜晚城市",
        size="1024x1024",
    )
print(result.data[0].url)

图片响应

response_format=url 返回平台存储 URL；response_format=b64_json 返回 Base64 且不写入图片存储。

json

{
  "created": 1784426400,
  "data": [
    {
      "url": "https://koimg.com/storage/images/example.webp",
      "b64_json": null,
      "revised_prompt": null
    }
  ]
}

图片会先扣除预计积分；部分图片生成失败时，未成功的数量会自动退回对应积分。

上传素材

上传参考图片或输入视频，获得可传给 JSON 接口的本站 URL。

POSThttps://koimg.com/v1/uploads

参数名	类型	必填	说明
file	`file`	是	要上传的文件
purpose	`string`	否	reference（默认，图片 ≤10MB）或 input_video（视频 ≤100MB）

bash

curl https://koimg.com/v1/uploads \
  -H "Authorization: Bearer $KOCODEIMG_API_KEY" \
  -F "file=@reference.png" \
  -F "purpose=reference"

json

{
  "object": "file",
  "purpose": "reference",
  "url": "https://koimg.com/storage/references/example.webp",
  "bytes": 248391
}

提交视频任务

视频为异步接口，成功提交返回 HTTP 202。保存响应中的 id，再通过查询接口轮询状态。参考图片和输入视频必须先通过 /uploads 上传。

POSThttps://koimg.com/v1/videos

请求参数

参数名	类型	必填	说明
model	`string`	否	视频模型 ID；默认 sora-2，建议先查询 /models
prompt	`string`	是	视频描述，最多 4,000 字符
seconds	`integer\|string`	否	时长 1-60 秒；模型不支持时会使用模型默认值
size	`string`	否	默认 16:9；支持模型接受的比例或像素尺寸
mode	`string`	否	text2video、image2video 或 video_edit；通常可根据素材自动判断
resolution	`string`	否	如 720p、1080p 或 4K；取决于模型
generate_audio	`boolean`	否	是否生成音频；取决于模型
reference_images	`string[]`	否	由 /uploads 返回的参考图片 URL
input_video_url	`string`	否	由 /uploads 返回的输入视频 URL

bash

curl https://koimg.com/v1/videos \
  -H "Authorization: Bearer $KOCODEIMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "日出时分宁静的山间湖泊，电影感航拍",
    "seconds": 8,
    "size": "16:9"
  }'

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "prompt": "日出时分宁静的山间湖泊，电影感航拍",
  "seconds": 8,
  "size": "16:9",
  "created_at": 1784426400,
  "completed_at": null,
  "error": null,
  "output": null
}

查询与删除视频任务

GEThttps://koimg.com/v1/videos/{video_id}

DELETEhttps://koimg.com/v1/videos/{video_id}

状态可能为 queued、processing、complete 或 failed。完成后，output 包含视频 URL，可能同时包含封面 URL。 DELETE 返回 204，仅从用户历史中删除记录，不会取消已经提交到上游的任务。

bash

VIDEO_ID="550e8400-e29b-41d4-a716-446655440000"

curl "https://koimg.com/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $KOCODEIMG_API_KEY"

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "object": "video",
  "model": "sora-2",
  "status": "complete",
  "progress": 100,
  "output": [
    {"type": "video", "url": "https://koimg.com/storage/videos/example.mp4"},
    {"type": "poster", "url": "https://koimg.com/storage/videos/example.jpg"}
  ]
}

python

import os
import time
import httpx

api_key = os.environ["KOCODEIMG_API_KEY"]
video_id = "550e8400-e29b-41d4-a716-446655440000"
headers = {"Authorization": f"Bearer {api_key}"}

with httpx.Client(base_url="https://koimg.com/v1", headers=headers, timeout=30.0) as client:
    while True:
        task = client.get(f"/videos/{video_id}").raise_for_status().json()
        if task["status"] == "complete":
            print(task["output"][0]["url"])
            break
        if task["status"] == "failed":
            raise RuntimeError(task.get("error") or "video generation failed")
        time.sleep(3)

错误结构

业务错误使用 OpenAI 风格对象并包在 FastAPI 的 detail 字段内。参数校验错误可能返回 FastAPI 标准的 detail 数组。

json

{
  "detail": {
    "error": {
      "message": "Invalid API key",
      "type": "invalid_request_error",
      "code": "invalid_api_key"
    }
  }
}

状态码

状态码	含义	建议
202	视频任务已接受	保存 id 并轮询任务状态
400	模型、素材或请求不符合要求	读取 detail.error.message 并修正请求
401	缺少或无效的 API Key	检查 Authorization Bearer 请求头
402	积分不足	充值、签到或降低生成规格
403	当前套餐无权使用模型	更换模型或升级套餐
404	视频任务不存在	确认任务属于当前 API Key 对应账号
422	字段类型或长度校验失败	检查 detail 数组中的 loc、msg 和 ctx
429	API Key 配额已用尽	等待配额周期重置或调整密钥配额
502	所有生成提供方均失败	稍后重试；持续失败时联系支持