Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

API reference

Authentication

Create an account and get an API key without a browser: register_account returns a live key instantly; the emailed-code flow (device_login_start + device_login_complete) signs an existing account in and mints a new key.

Create account and get API key

POST /v1/auth/register

Creates an account with a default project and returns a live secret API key (pv_live_) instantly. No browser or signup form needed.

The password is optional: omit it for a passwordless (agent) account; the owner can set one later through the password-reset flow to enable dashboard login. Keys are hashed server-side, so the raw key is shown only in this response.

The account starts unverified and a verification email is sent. Until the email is verified the account can store at most 5 images (email_verification_required), and video, audio, generation and editing are unavailable. Free-plan limits apply: 200 MB storage, 500 uploads a month, 1 GB bandwidth a month; see pricing.

Emails are lowercased; disposable email domains are refused. All /v1/auth/* endpoints share a limit of 5 requests per minute per IP.

Authentication

None. This endpoint is public.

Request body

application/json, required

Request body
Name Type Required Description
email string (email) Required

An address you can receive the verification email at.

password string Optional

Optional. Omit for a passwordless account; provide (min 8 chars) to enable password login immediately.

min length 8

Responses

  • 201

    Account created. Store default_project.api_keys.live now: it is never shown again.

  • 400

    invalid_json: the body is not valid JSON. validation_error: email missing or malformed, or password shorter than 8 characters. disposable_email: the email domain is a disposable-mail provider.

  • 409

    email_taken: an account with this email (or the same Gmail inbox under another spelling) already exists. Use device_login_start to sign in and get a key.

  • 429

    rate_limit_exceeded: more than 5 /v1/auth/* requests per minute from this IP. Honour Retry-After.

Request
curl -X POST https://api.pixelvault.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
  "email": "dev@example.com",
  "password": "your-secure-password"
}'
Response 201
{
  "data": {
    "account_id": "acct_abc123",
    "email": "dev@example.com",
    "email_verified": false,
    "password_set": false,
    "plan": "free",
    "default_project": {
      "id": "proj_xyz789",
      "name": "Default",
      "api_keys": {
        "live": "pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Start email-code sign-in

POST /v1/auth/device/start

Step 1 of a passwordless sign-in that needs no browser, for tools and agents that have an account but no key. Emails a 6-digit code (valid 10 minutes) to the address; creates the account first if the email is new, exactly like register_account. Finish with device_login_complete.

At most one code per 60 seconds per account; disposable email domains are rejected. Needs a person (or a mailbox the caller controls) to read the code. All /v1/auth/* endpoints share a limit of 5 requests per minute per IP.

Authentication

None. This endpoint is public.

Request body

application/json, required

Request body
Name Type Required Description
email string (email) Required

The account email; a new address creates a passwordless account.

Responses

  • 200

    Code sent

  • 400

    invalid_json: the body is not valid JSON. validation_error: email missing or malformed. disposable_email: the email domain is a disposable-mail provider.

  • 409

    email_taken: the address is another spelling of an existing account's Gmail inbox; sign in with the address that was registered.

  • 429

    rate_limited: a code was sent to this account in the last 60 seconds. rate_limit_exceeded: more than 5 /v1/auth/* requests per minute from this IP.

  • 500

    server_error: the account could not be created; retry.

Request
curl -X POST https://api.pixelvault.dev/v1/auth/device/start \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com"}'
Response 200
{
  "data": {
    "sent": true
  }
}

Exchange the emailed code for an API key

POST /v1/auth/device/complete

Step 2 of the email-code sign-in. Validates the code (3 attempts, single use), marks the email verified, and returns a new live secret API key for the account's default project. The key is shown once.

Each call mints an additional key (default label PixelVault Desktop; list and revoke them with list_keys / revoke_key), unless replace_existing is true, which deletes the older secret keys that share the same label so reconnecting does not pile them up.

Authentication

None. This endpoint is public.

Request body

application/json, required

Request body
Name Type Required Description
email string (email) Required
code string Required

The 6-digit code from the email.

label string Optional

Name for the new key, trimmed and cut to 40 characters. Shown in the dashboard and in list_keys.

Default: PixelVault Desktop

max length 40

replace_existing boolean Optional

Delete older secret keys with the same label after minting this one.

Default: false

Responses

Request
curl -X POST https://api.pixelvault.dev/v1/auth/device/complete \
  -H "Content-Type: application/json" \
  -d '{
  "email": "dev@example.com",
  "code": "123456",
  "label": "my-agent",
  "replace_existing": true
}'
Response 200
{
  "data": {
    "account_id": "acct_abc123",
    "key_id": "key_abc123",
    "api_key": "pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "project_id": "proj_xyz789",
    "email": "dev@example.com",
    "email_verified": true
  }
}