Omni API Docs

快速开始

创建第一个 Omni API 任务。

快速开始

这一页展示从 API Key 到任务结果的最短路径。

1. 创建 API Key

打开 Console，使用 Google 或邮箱登录，然后创建 API Key。正式产品里应把 API Key 保存在服务端。

export OMNI_API_KEY="your_api_key"
export OMNI_API_BASE="https://omniapi.net"

下面的 Shell 示例需要安装 curl、jq 和 uuidgen。

2. 查看模型

curl "$OMNI_API_BASE/api/omni/models"

响应会包含模型组、任务类型、输入 schema 和输出 schema。公开目录只展示已经 ready 的模型组。

3. 创建文生图任务

文生图任务不需要上传文件，可以直接创建。

export IDEMPOTENCY_KEY="$(uuidgen | tr '[:upper:]' '[:lower:]')"

CREATE_RESPONSE="$(curl -sS -X POST "$OMNI_API_BASE/api/omni/tasks/create" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_group":"omni-image-aio",
    "task_type":"text_to_image",
    "inputs":{
      "prompt":"a clean studio product photo",
      "reference_width":1024,
      "reference_height":1024,
      "aspect_ratio":"1:1"
    }
  }')"

export TASK_ID="$(printf '%s' "$CREATE_RESPONSE" | jq -r '.data.task.portal_task_id')"
printf '%s\n' "$CREATE_RESPONSE" | jq

每次创建请求都必须提供唯一的 Idempotency-Key。使用相同 key 和相同 payload 重试会安全地返回同一任务；相同 key 对应不同 payload 时会被拒绝。创建响应在 data.task 中返回任务，其中包含 portal_task_id 和 status。

4. 创建带文件的任务

编辑类任务先申请预签名上传地址并上传文件，再从返回的上传项构建稳定的 input_manifest。创建任务时复用同一个 client_request_id 作为幂等键，使上传对象与本次任务请求保持一致。

export INPUT_FILE="input.png"
export INPUT_SIZE="$(wc -c < "$INPUT_FILE" | tr -d ' ')"
export CLIENT_REQUEST_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"

PRESIGN_RESPONSE="$(curl -sS -X POST "$OMNI_API_BASE/api/omni/tasks/presign" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary "$(jq -nc \
    --arg request_id "$CLIENT_REQUEST_ID" \
    --argjson size "$INPUT_SIZE" \
    '{
      client_request_id:$request_id,
      model_group:"omni-image-aio",
      task_type:"single_image_edit",
      files:[{
        name:"source_image",
        filename:"input.png",
        content_type:"image/png",
        media_type:"image",
        size_bytes:$size
      }]
    }')")"

export UPLOAD_URL="$(printf '%s' "$PRESIGN_RESPONSE" | jq -r '.data.uploads[0].upload_url')"
export UPLOAD_CONTENT_TYPE="$(printf '%s' "$PRESIGN_RESPONSE" | jq -r '.data.uploads[0].upload_headers["content-type"]')"

curl -sS -X PUT "$UPLOAD_URL" \
  -H "Content-Type: $UPLOAD_CONTENT_TYPE" \
  --data-binary @"$INPUT_FILE"

INPUT_MANIFEST="$(printf '%s' "$PRESIGN_RESPONSE" | jq -c '{
  items:[.data.uploads[] | del(.upload_url,.upload_method,.upload_headers,.expires_at)]
}')"

CREATE_RESPONSE="$(curl -sS -X POST "$OMNI_API_BASE/api/omni/tasks/create" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Idempotency-Key: $CLIENT_REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data-binary "$(jq -nc \
    --argjson manifest "$INPUT_MANIFEST" \
    '{
      model_group:"omni-image-aio",
      task_type:"single_image_edit",
      inputs:{
        prompt:"make the product photo cleaner",
        reference_width:1024,
        reference_height:1024
      },
      input_manifest:$manifest
    }')")"

export TASK_ID="$(printf '%s' "$CREATE_RESPONSE" | jq -r '.data.task.portal_task_id')"
printf '%s\n' "$CREATE_RESPONSE" | jq

5. 查询状态

while :; do
  TASK_RESPONSE="$(curl -sS "$OMNI_API_BASE/api/omni/tasks/$TASK_ID" \
    -H "Authorization: Bearer $OMNI_API_KEY")"
  TASK_STATUS="$(printf '%s' "$TASK_RESPONSE" | jq -r '.data.task.status')"
  printf 'status=%s\n' "$TASK_STATUS"
  case "$TASK_STATUS" in
    completed|failed|canceled) break ;;
  esac
  sleep 3
done

只在任务为 pending 或 running 时继续轮询；任务进入 completed、failed 或 canceled 后停止。Public API 不提供预计等待时间或全局排队名次。

6. 下载文件输出

图像、视频或音频任务完成后，通过专用接口获取最新输出地址并下载对应的 download_url。输出项的 expires_in_seconds 为 0 时表示公开访问；正数表示签名地址的有效秒数。

OUTPUT_RESPONSE="$(curl -sS "$OMNI_API_BASE/api/omni/tasks/$TASK_ID/output-urls" \
  -H "Authorization: Bearer $OMNI_API_KEY")"
export DOWNLOAD_URL="$(printf '%s' "$OUTPUT_RESPONSE" | jq -r '.data.output.outputs[0].download_url')"

curl -sS -L "$DOWNLOAD_URL" -o output.bin

文本或 JSON 类型的结果直接位于 data.task.outputs[] 的 text、value 等字段中，不需要通过对象存储下载。