Hydracept

Quick Start

Hydracept is an execution control plane for software teams and coding agents that need to call external AI capabilities through one public API. Games and media are important capability families, not the whole product.

Discover capabilities, submit invoke or durable jobs, track progress, download artifacts, and keep a receipt for every run. BYOK is 0% Hydracept fee; managed inference is provider price + 6%. Eligible durable text jobs use deferred processing at 50% of standard token rates.

Current client release: 0.5.4 (see Migrating to 0.5.0 if you are below 0.5.0).

5-minute path

For one asset: python -m hydracept run image.generate.v1 --prompt "..." --json (composes init). For a full walkthrough, see 5-minute game asset. One-off tasks are supported — a single capability call does not require an integration commitment.

Activate

Pick one:

  1. CLI bootstrap (recommended): pip install -U hydracept then python -m hydracept init --apply --yes --json. Init infers the current git/workspace project when you are already signed in. Browser project selection is only required when that inference is ambiguous.
  2. Studio (browser): app.hydracept.com/login — sign in with GitHub or Google, then generate in Studio or create an API key for a library, script, or backend. Manage plans at Studio Billing.
  3. Agents / headless: python -m hydracept init --apply --yes --json (or use an existing key out of band with HYDRACEPT_API_KEY).

For coding agents, interaction_required is a hard human boundary. If presentation.agentAction is present_and_yield and stdio MCP exposes hydracept_interaction_surface, invoke that surface once with the supplied context and stop the turn. Otherwise present action.url verbatim. In either case, stop until the human completes activation; only then run afterCompletion.command / --wait.

See Authentication for workspace files (.hydracept/project.json, secrets, lazy BYOK) and CI mode (init --apply --yes --json --ci).

Public API: https://api.hydracept.com

Configuration directory (CLI): .hydracept/

Environment variables: HYDRACEPT_API_URL, HYDRACEPT_API_KEY, HYDRACEPT_PROJECT, HYDRACEPT_ENVIRONMENT

BYOK: Your Hydracept API key authenticates your application, while your provider key pays for inference. Run python -m hydracept smoke (trial budget or BYOK — a real image job) before connecting BYOK — see Connections / BYOK and Billing & plans.

CLI


pip install -U hydracept

# Prefer the module form if `hydracept` is not on PATH (common on Windows):
python -m hydracept init                              # human — opens connect URL when needed
python -m hydracept init --apply --yes --json         # agents
python -m hydracept init --apply --yes --json --ci    # CI (setup grants)
python -m hydracept doctor
python -m hydracept smoke
python -m hydracept verify
python -m hydracept agent-context

configure and quickstart are deprecated aliases for init. Device login (python -m hydracept login) still works for advanced flows.

No-agent integrations

For PHP, .NET, TypeScript, Python or direct HTTP, create a named key at Studio API keys. Copy HYDRACEPT_API_KEY and HYDRACEPT_PROJECT once, then store them in your server-side environment. See Library integration.

SDKs

The Python SDK and CLI are available now:


pip install -U hydracept
python -m hydracept --help

The TypeScript SDK is also available:


npm install @hydracept/sdk

.NET SDK


dotnet add package Hydracept.Client

Discover capabilities


curl -sS -H "Authorization: Bearer $HYDRACEPT_API_KEY" \
  https://api.hydracept.com/v1/capabilities

The live catalog is GET /v1/capabilities (or python -m hydracept agent-context). Do not freeze a launch-key list from the docs index.

See Capabilities for how capability keys work.

Invoke text synchronously

POST /v1/capabilities/text.general.fast.v1/invoke returns the generated text

directly. Omit context: a bound API key supplies its own project and environment.

If you send an explicit context, it must match the credential or the request is

rejected with 403 before admission.


curl -sS -X POST \
  -H "Authorization: Bearer $HYDRACEPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "messages": [
        { "role": "user", "content": "Write a silly haiku about a sleepy robot." }
      ],
      "maxOutputTokens": 64
    },
    "execution": {
      "executionPreference": "automatic",
      "executionConstraints": { "maxCostUsd": 0.02 }
    },
    "idempotencyKey": "<uuid-v4>"
  }' \
  https://api.hydracept.com/v1/capabilities/text.general.fast.v1/invoke

The response contains typedOutput as a string matching the descriptor's

outputSchemas.text, plus executionId, receiptId, resolvedProvider, and

resolvedModel. Reusing the same idempotencyKey returns the same execution and

receipt instead of charging again. Use GET /v1/public/receipts/{receiptId} to

retrieve the receipt.

For image production (Sheet & Slice, transparent output, variants), see Image production.

For Unity 6 Editor integration (generate, sheet slice, import with provenance), see Unity integration.

Submit a durable job


JOB_JSON=$(curl -sS -X POST \
  -H "Authorization: Bearer $HYDRACEPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "productId": "my-product",
      "projectId": "cpr_...",
      "environment": "development"
    },
    "input": { "prompt": "cute slime icon" },
    "execution": { "executionPreference": "automatic" },
    "idempotencyKey": "demo-1"
  }' \
  https://api.hydracept.com/v1/capabilities/image.generate.v1/jobs)

echo "$JOB_JSON"
JOB_ID=$(printf '%s' "$JOB_JSON" | python -c "import sys,json; print(json.load(sys.stdin)['jobId'])")

The submit response is a HydraceptJob object. Use jobId from that payload for poll and receipt calls.

Poll the job


curl -sS -H "Authorization: Bearer $HYDRACEPT_API_KEY" \
  https://api.hydracept.com/v1/jobs/$JOB_ID

Poll until status is succeeded, failed, or canceled.

Fetch the receipt


curl -sS -H "Authorization: Bearer $HYDRACEPT_API_KEY" \
  https://api.hydracept.com/v1/jobs/$JOB_ID/receipt

Find and inspect later

If an agent no longer has the ID—or a user simply says “the last job failed”—query project history instead of asking the human to find it:


curl -sS -H "Authorization: Bearer $HYDRACEPT_API_KEY" \
  "https://api.hydracept.com/v1/projects/cpr_.../jobs?outcome=failed&limit=10"

The list is prompt-free. Once the relevant job is identified, intentionally inspect only that job with GET /v1/jobs/{jobId}. The prompt that was executed is requestSnapshot.input.prompt. MCP provides the shorter agent loop and returns it as executedPrompt:


hydracept_jobs_find(intent="failed")
→ hydracept_job_inspect(job_id)

For prior successful outputs use intent="reusable"; Hydracept highlights an explicitly selected artifact when one exists. A retry always uses a new idempotency key.

See Durable Jobs & Receipts for filters, artifacts, inspection, and outputs.

Next