MediaAsync 外部接入文档

MediaAsync 是异步媒体生成服务。调用方通过公开 model 提交图片、视频或图片工具任务，服务立即返回任务 id，后台 Worker 完成 Provider 调用、轮询、产物上传后，再通过查询接口返回最终产物 URL。

快速开始

默认本地服务地址：

https://media.kitt.tools

所有业务 API 都需要 Bearer token。API token 由服务管理员在 Admin 中创建，形如 sk_...。

Authorization: Bearer sk_...

sk_... 只用于访问 MediaAsync，不是上游 Provider key。创建任务默认使用调用方自带 Provider key 的 BYOK/OpenAI-compatible 路由：

X-MediaAsync-Provider-Key: upstream-provider-key
X-MediaAsync-Provider-Base-URL: https://api.example.com/v1

X-MediaAsync-Provider-Base-URL 可省略，省略时使用服务端 [byok].base_url。调用方传入的 base URL 必须是公网 HTTP(S) 地址；localhost、私网 IP、Docker/container 主机名、单标签主机名、.local、.internal 等内网目标都会被拒绝。

最小图片生成请求：

curl -sS https://media.kitt.tools/v1/images/generations \
  -H "Authorization: Bearer sk_..." \
  -H "X-MediaAsync-Provider-Key: upstream-provider-key" \
  -H "X-MediaAsync-Provider-Base-URL: https://api.example.com/v1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a small ceramic teapot on a walnut table",
    "size": "1024x1024",
    "output_format": "png"
  }'

创建成功会返回异步任务：

{
  "id": "0f0d4e89-...",
  "object": "image.generation",
  "status": "queued"
}

随后轮询任务：

curl -sS https://media.kitt.tools/v1/images/0f0d4e89-... \
  -H "Authorization: Bearer sk_..."

接入流程

1. 调用 GET /v1/models/catalog 获取可用模型、能力和价格信息。
2. 选择路由：默认 BYOK/OpenAI-compatible 需要传上游 Provider key；托管渠道需要传 X-MediaAsync-Route: managed。
3. 选择支持目标能力的公开 model，不要传内部 format 或渠道 ID。
4. 调用对应的创建接口，拿到任务 id。
5. 使用单任务查询或批量查询轮询状态。
6. 当 status 为 succeeded 时，从 data[].url 获取产物。
7. 当 status 为 failed 或 canceled 时，根据业务需要重试或结束。

公共页面

/playground.html 和 /dashboard.html 是公开页面外壳，页面内实际调用业务 API 时仍需要 sk_... token。

认证

所有创建、查询、取消、重试、批量查询、模型目录和 quote 接口都使用：

Authorization: Bearer sk_...

缺失或无效 token 返回：

{
  "error": {
    "message": "missing or invalid API key"
  }
}

Bearer token 只能访问同一个 API key 创建的任务。不同 key 创建的任务在查询、取消、重试和批量查询中不可见。

上游路由

创建任务有两套上游路由：

BYOK 路由目前只支持 OpenAI-compatible 图片生成和图片编辑，即 /v1/images/generations 和 /v1/images/edits。请求必须包含：

X-MediaAsync-Provider-Key: upstream-provider-key

如果服务端没有配置 [byok].base_url，请求还必须包含：

X-MediaAsync-Provider-Base-URL: https://api.example.com/v1

托管渠道请求不要传 X-MediaAsync-Provider-Key 或 X-MediaAsync-Provider-Base-URL，否则会返回 400。Provider-compatible 入口、视频、图片工具和非 OpenAI-compatible 能力必须使用：

X-MediaAsync-Route: managed

模型目录

简化模型列表

GET /v1/models

curl -sS https://media.kitt.tools/v1/models \
  -H "Authorization: Bearer sk_..."

响应：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "model",
      "created": 1778470000,
      "owned_by": "openai"
    }
  ]
}

完整模型目录

GET /v1/models/catalog

curl -sS https://media.kitt.tools/v1/models/catalog \
  -H "Authorization: Bearer sk_..."

响应重点字段：

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "model",
      "owned_by": "openai",
      "display_name": "GPT Image 2",
      "task_type": "image.generate",
      "task_types": ["image.generate", "image.edit"],
      "capabilities": { "image": true, "provider": "openai" },
      "channels": [
        {
          "channel_id": "openai-main",
          "provider_format": "openai",
          "provider_model": "gpt-image-2",
          "enabled": true
        }
      ],
      "pricing_profiles": [
        {
          "id": "default-gpt-image-2-image-generate",
          "version": 1,
          "channel_id": null,
          "task_type": "image.generate",
          "currency": "usd",
          "rules": [{ "type": "per_image", "micro_usd_per_image": 40000 }],
          "enabled": true
        }
      ]
    }
  ]
}

调用方只需要传公开 model。模型绑定、真实 Provider、Provider model、渠道优先级和重试策略由 MediaAsync 内部决定。

通用响应

创建任务响应

{
  "id": "task-id",
  "object": "image.generation",
  "status": "queued"
}

object 随任务类型变化，常见值包括：

查询任务响应

轮询接口返回的是任务当前快照。处理中时 data 通常为空数组；成功后 data 是产物数组；失败或取消时 data 通常为空，错误信息在 error。

处理中示例：

{
  "id": "task-id",
  "object": "image.generation",
  "status": "running",
  "stage": "provider_processing",
  "progress": 40,
  "model": "gpt-image-2",
  "task_type": "image.generate",
  "data": [],
  "error": null,
  "created_at": 1778470000,
  "updated_at": 1778470010,
  "completed_at": null
}

成功示例：

{
  "id": "task-id",
  "object": "image.edit",
  "status": "succeeded",
  "stage": "succeeded",
  "progress": 100,
  "model": "gpt-image-2",
  "task_type": "image.edit",
  "data": [
    {
      "id": "artifact-id",
      "object": "image",
      "url": "https://cdn.example.com/result.png",
      "content_type": "image/png",
      "size_bytes": 123456
    }
  ],
  "error": null,
  "created_at": 1778470000,
  "updated_at": 1778470030,
  "completed_at": 1778470030
}

失败示例：

{
  "id": "task-id",
  "object": "image.generation",
  "status": "failed",
  "stage": "failed",
  "progress": 100,
  "model": "gpt-image-2",
  "task_type": "image.generate",
  "data": [],
  "error": {
    "message": "provider error: upstream request failed"
  },
  "created_at": 1778470000,
  "updated_at": 1778470030,
  "completed_at": 1778470030
}

响应字段：

data 数组里的每一项是一个 artifact：

常见 data 形态：

图片任务成功：

"data": [
  {
    "id": "artifact-image-1",
    "object": "image",
    "url": "https://cdn.example.com/tasks/task-id/image/artifact.png",
    "content_type": "image/png",
    "size_bytes": 345678
  }
]

多图任务成功：

"data": [
  {
    "id": "artifact-image-1",
    "object": "image",
    "url": "https://cdn.example.com/tasks/task-id/image/1.png",
    "content_type": "image/png",
    "size_bytes": 345678
  },
  {
    "id": "artifact-image-2",
    "object": "image",
    "url": "https://cdn.example.com/tasks/task-id/image/2.png",
    "content_type": "image/png",
    "size_bytes": 331024
  }
]

视频任务成功：

"data": [
  {
    "id": "artifact-video-1",
    "object": "video",
    "url": "https://cdn.example.com/tasks/task-id/video/result.mp4",
    "content_type": "video/mp4",
    "size_bytes": 8923441
  }
]

矢量化任务成功时通常返回 SVG：

"data": [
  {
    "id": "artifact-svg-1",
    "object": "image",
    "url": "https://cdn.example.com/tasks/task-id/image/result.svg",
    "content_type": "image/svg+xml",
    "size_bytes": 48210
  }
]

调用方判断产物类型时优先看 content_type。例如 content_type 为 video/mp4 时按视频处理，为 image/svg+xml 时按 SVG 文本/矢量图处理。

status 取值：

stage 取值：

图片生成

POST /v1/images/generations

Content-Type: application/json

默认 BYOK 路由需要传 X-MediaAsync-Provider-Key，也可传 X-MediaAsync-Provider-Base-URL 覆盖默认上游。BYOK 只支持这个图片生成接口和 /v1/images/edits。要改用 Admin 托管渠道，在请求头加 X-MediaAsync-Route: managed，且不要传 Provider key 相关请求头。

示例：

curl -sS https://media.kitt.tools/v1/images/generations \
  -H "Authorization: Bearer sk_..." \
  -H "X-MediaAsync-Provider-Key: upstream-provider-key" \
  -H "X-MediaAsync-Provider-Base-URL: https://api.example.com/v1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a clean product photo of a tiny ceramic teapot",
    "size": "1024x1024",
    "output_format": "png"
  }'

图片编辑

POST /v1/images/edits

图片编辑支持 JSON 和 multipart form-data。

默认 BYOK 路由需要传 X-MediaAsync-Provider-Key，也可传 X-MediaAsync-Provider-Base-URL 覆盖默认上游。BYOK 只支持这个图片编辑接口和 /v1/images/generations。要改用 Admin 托管渠道，在请求头加 X-MediaAsync-Route: managed。

JSON 请求

JSON 示例：

curl -sS https://media.kitt.tools/v1/images/edits \
  -H "Authorization: Bearer sk_..." \
  -H "X-MediaAsync-Provider-Key: upstream-provider-key" \
  -H "X-MediaAsync-Provider-Base-URL: https://api.example.com/v1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "turn the sketch into a clean watercolor illustration",
    "image": {
      "filename": "source.png",
      "mime_type": "image/png",
      "data": "<base64-without-data-url-prefix>"
    },
    "size": "1024x1024",
    "output_format": "png"
  }'

Multipart 请求

Multipart 示例：

curl -sS https://media.kitt.tools/v1/images/edits \
  -H "Authorization: Bearer sk_..." \
  -H "X-MediaAsync-Provider-Key: upstream-provider-key" \
  -H "X-MediaAsync-Provider-Base-URL: https://api.example.com/v1" \
  -F "model=gpt-image-2" \
  -F "prompt=turn the sketch into a clean watercolor illustration" \
  -F "[email protected];type=image/png" \
  -F "size=1024x1024" \
  -F "output_format=png"

图片工具

这些接口使用 JSON。image 和 mask 字段使用下方“媒体输入引用格式”。

图片工具目前使用 Admin 托管渠道，请传 X-MediaAsync-Route: managed。

示例：

curl -sS https://media.kitt.tools/v1/images/upscale \
  -H "Authorization: Bearer sk_..." \
  -H "X-MediaAsync-Route: managed" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft-crisp-upscale",
    "image": { "url": "https://example.com/source.png" },
    "mode": "crisp"
  }'

视频生成

POST /v1/videos

Content-Type: application/json

视频生成目前使用 Admin 托管渠道，请传 X-MediaAsync-Route: managed。

示例：

curl -sS https://media.kitt.tools/v1/videos \
  -H "Authorization: Bearer sk_..." \
  -H "X-MediaAsync-Route: managed" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-veo-3.1-generate-preview",
    "prompt": "a cinematic product shot of a ceramic teapot",
    "seconds": "6",
    "size": "1280x720"
  }'

查询、批量查询、取消和重试

图片任务查询：

curl -sS https://media.kitt.tools/v1/images/task-id \
  -H "Authorization: Bearer sk_..."

视频任务查询：

curl -sS https://media.kitt.tools/v1/videos/task-id \
  -H "Authorization: Bearer sk_..."

批量查询：

curl -sS https://media.kitt.tools/v1/media/batch \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["task-id-1", "task-id-2"] }'

批量响应：

{
  "object": "list",
  "data": [
    {
      "id": "task-id-1",
      "object": "image.edit",
      "status": "running",
      "stage": "provider_processing",
      "progress": 40,
      "model": "gpt-image-2",
      "task_type": "image.edit",
      "data": [],
      "error": null,
      "created_at": 1778470000,
      "updated_at": 1778470010,
      "completed_at": null
    }
  ],
  "missing": ["task-id-2"]
}

/v1/media/batch 的 data 数组与单任务查询响应结构一致，只是一次返回多个任务快照。missing 表示这些 ID 对当前 API key 不可见，可能是任务不存在，也可能是由其他 API key 创建。批量查询不会因为部分 ID 缺失而整体失败。

取消：

curl -sS -X POST https://media.kitt.tools/v1/images/task-id/cancel \
  -H "Authorization: Bearer sk_..."

重试：

curl -sS -X POST https://media.kitt.tools/v1/images/task-id/retry \
  -H "Authorization: Bearer sk_..."

视频任务使用 /v1/videos/{video_id}/cancel 和 /v1/videos/{video_id}/retry。

cancel 只允许 queued 或 running 任务；retry 只允许 failed 或 canceled 任务。

媒体输入引用格式

图片编辑、参考图、参考视频和图片工具输入通常支持以下格式。

URL 字符串：

"https://example.com/source.png"

URL 对象：

{ "url": "https://example.com/source.png" }

Data URL：

"data:image/png;base64,iVBORw0KGgo..."

Base64 对象：

{
  "filename": "source.png",
  "mime_type": "image/png",
  "data": "iVBORw0KGgo..."
}

data 字段传纯 base64，不需要 data:image/png;base64, 前缀。

内部文件引用：

{
  "kind": "mediaasync_file",
  "file_id": "file_..."
}

普通第三方最常用的是 HTTP URL、data URL、base64 对象，或图片编辑 multipart 文件上传。

Quote 估价

POST /internal/quote

Content-Type: application/json

请求：

{
  "model": "gpt-image-2",
  "task_type": "image.generate",
  "channel_id": null,
  "input": {
    "prompt": "a small ceramic teapot",
    "n": 1,
    "quality": "high"
  }
}

响应：

{
  "quote_id": "qt_...",
  "quote_version": 1,
  "currency": "usd",
  "estimated_cost_usd": "0.040000",
  "max_cost_usd": "0.040000",
  "expires_at": "2026-05-11T03:40:00Z",
  "pricing_snapshot": {
    "model": "gpt-image-2",
    "task_type": "image.generate",
    "channel_policy": "auto",
    "pricing_profile": "default-gpt-image-2-image-generate"
  }
}

Quote 是估价能力，不代表 MediaAsync 内部完成扣费。余额冻结、扣款、退款通常由上游网关或业务系统负责。

Provider-compatible API

Provider-compatible 入口用于降低已有调用方迁移成本。请求体更接近供应商原生格式，但不会绕过 MediaAsync 的模型目录、渠道调度、重试、轮询、上传和 artifact 状态机。

这些入口仍要求 Authorization: Bearer sk_...。创建成功返回 MediaAsync 任务 { id, object, status }，最终结果仍通过 MediaAsync 查询接口轮询。

错误和状态码

错误响应：

{
  "error": {
    "message": "bad request: model gpt-image-2 not found"
  }
}

常见 HTTP 状态：

重要约定

• 调用方只传公开 model，不要传内部 format、物理渠道 ID 或持久化字段。Provider key 只在默认 BYOK 创建请求中通过 X-MediaAsync-Provider-Key 传入；Managed 路由不要传 Provider key。
• 创建接口是异步接口，创建成功不代表生成完成。
• 最终产物 URL 来自 data[].url，可能是本地 /files/* URL，也可能是 R2/CDN URL。
• Provider-compatible 入口的响应仍是 MediaAsync 异步任务响应，不保证完全复刻 Provider 原始同步响应。
• MediaAsync 不做终端用户体系、余额扣减或内容审核；这些通常由上游网站、网关和 Provider 策略负责。