Seele Public API

Intro

The Seele Public API provides a stable, API-key based interface for generating and iterating on any type of content programmatically via jobs.

Typical integration flow:

1. Create an API key in the Seele developer console.
2. Upload reference files when needed with POST /v2/api/files.
3. Start a generation job with POST /v2/api/jobs.
4. Optionally add a follow-up step to an existing job with POST /v2/api/jobs/{job_id}/steps.
5. Poll GET /v2/api/jobs/{job_id} until status is finished.

Base URL

https://openapi.seeles.ai

Authentication

All public API endpoints require Bearer authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Create and manage API keys in the Seele developer console.

Endpoints

Contract notes

• All documented endpoints are versioned under /v2/api.
• job_id and file_id are opaque public identifiers.
• Successful responses return ok: true.
• Failed responses return ok: false with an error object.
• Only rely on fields explicitly documented on this page.
• Additional non-contract fields may appear in some responses for product integration or display convenience and may change without notice.

Response envelope

{
  "ok": true,
  "data": {
    "job_id": "job_123",
    "meta": {
      "platform_url": "https://www.seeles.ai/workspace/job_123"
    }
  }
}

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Authentication

Pass the API key from the Seele developer console in the Authorization header as a Bearer token.

Request example

curl https://openapi.seeles.ai/v2/api/jobs \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a cozy cat farming game",
    "model": "Seele02-flash",
    "engine": "threejs"
  }'

Upload File

POST /v2/api/files creates a temporary upload session. Upload the raw file bytes to the returned upload_url before upload_url_expires_at, then pass the returned file_id to /v2/api/jobs or /v2/api/jobs/{job_id}/steps.

Request fields

curl https://openapi.seeles.ai/v2/api/files \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "reference.png",
    "content_type": "image/png",
    "size": 428731
  }'

curl "$UPLOAD_URL" \
  -X PUT \
  -H "Content-Type: image/png" \
  --data-binary "@reference.png"

Response example

{
  "ok": true,
  "data": {
    "file_id": "0123456789abcdef0123456789abcdef",
    "upload_url": "https://...presigned-put-url...",
    "upload_url_expires_at": "2026-04-17T00:45:00.000Z",
    "upload_headers": {
      "Content-Type": "image/png"
    },
    "filename": "reference.png",
    "content_type": "image/png",
    "size": 428731
  }
}

Create Job

Start a new generation job request from an initial prompt. Store the returned job_id and reuse it for later status checks or step requests. The accepted response can also include meta.platform_url, a hosted Seele workspace link that product users can open as a sandbox for review or further iteration. engine accepts threejs, unity, or unreal as the runtime environment, and unreal is available to subscription users only. Seele02-pro is available to subscription users; otherwise the request returns 403.

Request fields

Request example

curl https://openapi.seeles.ai/v2/api/jobs \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a cozy cat farming game with planting and fishing",
    "model": "Seele02-flash",
    "engine": "threejs",
    "generation_model": "seedream5lite",
    "file_ids": ["0123456789abcdef0123456789abcdef"]
  }'

Response example

{
  "ok": true,
  "data": {
    "job_id": "job_123",
    "meta": {
      "platform_url": "https://www.seeles.ai/workspace/job_123"
    }
  }
}

Response fields

Build workflow around job_id and later status. Treat meta.platform_url as a convenience field for product review flows, not as required contract for automation.

Status codes

Create Job Step

Submit a follow-up prompt step for an existing job using its public job_id. Successful responses follow the same shape as create and may also include meta.platform_url pointing to the updated workspace, plus a step_id for the new step. Seele02-pro is available to subscription users; otherwise the request returns 403.

Request fields

Request example

curl https://openapi.seeles.ai/v2/api/jobs/$JOB_ID/steps \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add a day-night cycle and a boss battle",
    "model": "Seele02-flash",
    "file_ids": ["fedcba9876543210fedcba9876543210"]
  }'

Response example

{
  "ok": true,
  "data": {
    "job_id": "job_123",
    "step_id": "step_456",
    "meta": {
      "platform_url": "https://www.seeles.ai/workspace/job_123"
    }
  }
}

Response fields

If the job is still processing, the API returns 409 instead of accepting the step request.

As with create, build automation around documented identifiers and status fields. Treat meta.platform_url as convenience product metadata.

Status codes

Error example

{
  "ok": false,
  "error": {
    "code": "JOB_ALREADY_PROCESSING",
    "message": "job is still generating, new steps are not allowed yet"
  }
}

Get Job Status

Query the current job state with a job_id. Poll this endpoint every 10–30 seconds until status becomes finished. Finished responses include summary, total_koin, an artifacts array with latest-turn generated output metadata, and meta.platform_url for opening the result in the Seele workspace interface.

Artifact metadata is returned for finished jobs, but direct artifact download URLs are gated by plan. API keys on Standard or above receive populated artifacts[].urls. Lower-tier keys receive urls: [] plus meta.artifact_urls_access_message, and can still preview the result through meta.platform_url.

Generation states

Request example

curl https://openapi.seeles.ai/v2/api/jobs/$JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Representative finished response for a lower-tier key

{
  "ok": true,
  "data": {
    "job_id": "job_123",
    "status": "finished",
    "summary": "A time detective puzzle with a boss room.",
    "total_koin": 125,
    "artifacts": [
      {
        "id": "artifact_789",
        "name": "Game Project",
        "description": "Generated Unity project package",
        "status": "ready",
        "urls": []
      }
    ],
    "meta": {
      "platform_url": "https://www.seeles.ai/workspace/job_123",
      "artifact_urls_access_message": "Upgrade to Standard or above to access artifact download URLs. You can preview the output from platform_url."
    }
  }
}

Response fields

For automation, rely on status and the documented output fields. Treat artifact URLs as plan-gated outputs: check whether artifacts[].urls is populated before starting a download, and fall back to meta.platform_url when only preview access is available.

Status codes

List Generation Models

Discover the available generation models before creating jobs or direct generations. Each entry declares its modality (tags), the minimum plan tier needed to use it (required_plan_tier), and which API surfaces accept it (supported_interfaces). Image and video models work with both /v2/api/generations and /v2/api/jobs; world and 3d models are currently jobs-only.

Request example

curl https://openapi.seeles.ai/v2/api/generation_models \
  -H "Authorization: Bearer YOUR_API_KEY"

Response example

{
  "ok": true,
  "data": {
    "generation_models": [
      {
        "id": "nanobanana",
        "label": "NanoBanana",
        "description": "Free image generation and single-reference editing; ...",
        "required_plan_tier": "free",
        "tags": ["image"],
        "supported_interfaces": ["generations", "jobs"]
      },
      {
        "id": "seedance1_5_720p",
        "label": "Seedance 1.5 720p",
        "description": "Standard text/image/video/audio generation, editing, and extension; ...",
        "required_plan_tier": "standard",
        "tags": ["video"],
        "supported_interfaces": ["generations", "jobs"],
        "capabilities": {
          "aspect_ratios": ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "adaptive"],
          "duration_seconds": { "min": 4, "max": 12, "allow_auto": true },
          "generate_types": ["text_to_video", "image_to_video_first_frame", "image_to_video_first_last_frame"]
        }
      },
      {
        "id": "marble_0.1-mini",
        "label": "Marble 0.1 Mini",
        "description": "Free world model; ...",
        "required_plan_tier": "free",
        "tags": ["world"],
        "supported_interfaces": ["jobs"]
      }
    ]
  }
}

Response fields

Status codes

Create Generation

Generate an image or video directly from a supported generation model, without creating a job. Image models usually finish synchronously and return status: completed with result.urls. Video models are asynchronous: the response returns queued or processing, and you poll GET /v2/api/generations/{generation_id} until the status becomes completed or failed. Billing is atomic: the estimated cost is frozen on acceptance, settled on success, and automatically released on failure.

Access is gated by plan. Models marked required_plan_tier: standard require an active subscription; free API keys receive 403 SUBSCRIPTION_REQUIRED before any billing happens. Models whose supported_interfaces do not include generations (world and 3d) are rejected with 400 UNSUPPORTED_GENERATION_MODEL and must be used through /v2/api/jobs.

Request fields

curl https://openapi.seeles.ai/v2/api/generations \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c2a84-unique-per-logical-request" \
  -d '{
    "generation_model": "nanobanana",
    "prompt": "A cozy reading nook with warm light, soft illustration style"
  }'

curl https://openapi.seeles.ai/v2/api/generations \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7bd31f02-unique-per-logical-request" \
  -d '{
    "generation_model": "seedance2_720p",
    "prompt": "A calm ocean wave rolling onto a sandy beach at sunrise",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'

Response example

{
  "ok": true,
  "data": {
    "generation_id": "495d160a-48f8-4942-86c7-193736f5b477",
    "status": "completed",
    "result": {
      "urls": ["https://...signed-download-url..."]
    },
    "billing": {
      "status": "settled",
      "estimatedCost": 0,
      "actualCost": 0
    }
  }
}

Response fields

Plan gating and unsupported model errors

{
  "ok": false,
  "error": {
    "code": "SUBSCRIPTION_REQUIRED",
    "message": "generation_model seedance1_5_720p requires an active subscription"
  }
}

{
  "ok": false,
  "error": {
    "code": "UNSUPPORTED_GENERATION_MODEL",
    "message": "generation_model marble_0.1-mini is not supported by POST /v2/api/generations (image/video models only); use /v2/api/jobs instead"
  }
}

Status codes

Get Generation

Poll a direct generation with its generation_id. For asynchronous video generations, poll every 10-30 seconds until status becomes completed or failed. Completed responses include result.urls once billing has settled. Failed generations include an error object, and any frozen billing hold is released automatically.

Request example

curl https://openapi.seeles.ai/v2/api/generations/$GENERATION_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Response example

{
  "ok": true,
  "data": {
    "generation_id": "1a8c9132-27ad-4221-8ab6-8c77bdb3ed5f",
    "status": "completed",
    "result": {
      "urls": ["https://...video-download-url..."]
    },
    "billing": {
      "status": "settled",
      "estimatedCost": 15,
      "actualCost": 15
    }
  }
}

Response fields

Status codes