Omni API Docs

Quickstart

Create your first Omni API task.

Quickstart

This page shows the shortest path from API key to task result.

1. Create an API key

Open Console, sign in with Google or email, then create an API key. Keep the key server-side when you build a product.

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

The shell examples below require curl, jq, and uuidgen.

2. List models

curl "$OMNI_API_BASE/api/omni/models"

The response includes model groups, task types, input schema, and output schema. Only ready model groups are shown on the public catalog.

3. Create a text-to-image task

Text-to-image tasks do not require a file upload and can be created directly.

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

Every create request requires a unique Idempotency-Key. Reusing the same key with the same payload safely returns the same task; reusing it with a different payload is rejected. The create response returns the task at data.task, including portal_task_id and status.

4. Create a file-based task

For edit workflows, request a signed upload, upload the file, then build the stable input_manifest from the returned upload item. The same client_request_id is used as the create idempotency key so the uploaded object belongs to that task request.

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. Poll task status

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

Poll only while the task is pending or running, then stop at completed, failed, or canceled. The Public API does not publish estimated wait times or a global queue position.

6. Download file outputs

For a completed image, video, or audio task, request fresh output URLs and download each download_url. An item-level expires_in_seconds of 0 means public access; a positive value is the signed URL lifetime.

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

Tasks with text or JSON outputs return them inline in data.task.outputs[] through fields such as text or value; they do not require an object-storage download.