API Reference

All requests require the X-API-Key header (except GET /api/health):

X-API-Key: dpp_api_8c1b2f3e4d5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e

Format: dpp_api_ prefix + 64 hex characters = 72 chars total. Get your key from the Keys dashboard — keys are shown once only, store them securely.

https://app.dickpicpro.com

Content-Type: application/json for all POST bodies. Responses use unescaped Unicode — emoji and non-ASCII characters pass through without \uXXXX escaping.

Every POST /api/analyze request must include an Idempotency-Key header. This protects against double-charging and duplicate submissions from network retries.

Contract

• Generate a unique value per logical request — UUIDv4, UUIDv7, ULID, KSUID, nanoid all work.
• Reuse the same key only for retries of the same request (same body).
• Server caches the response for 24 hours keyed by (account_id, idempotency_key).
• Replay returns the identical HTTP status + body with header X-Idempotent-Replay: true.

Header format

8–255 characters. Allowed: A-Z, a-z, 0-9, and _ - . :. No whitespace, no other punctuation.

Behavior

Asynchronous. Returns 202 immediately with a task_id; the final result arrives via webhook (recommended) or polling GET /api/status.

Required headers

X-API-Key:       dpp_api_...
Idempotency-Key: 01J4TM5P8H3Z9K2Y7Q1NBVCR6X
Content-Type:    application/json

Request body (JSON)

{
  "image": "<base64-encoded image>",   // required (unless dry_run=true)
  "prompt": {                            // optional — all fields have defaults
    "mode":             "standard",
    "language":         "en",
    "focus":            "auto",
    "style_category":   "basic",
    "style":            "neutral_supportive",
    "intensity":        "medium",
    "humiliation_type": "general",
    "closer":           false,
    "humor":            false,
    "emoji":            false,
    "no_positive":      false
  },
  "dry_run": false                       // optional — see Sandbox section
}

Response 202 Accepted

{
  "success": true,
  "data": {
    "task_id":        "dickpic_8c1b2f3e4d5a6b7c",
    "reservation_id": "rsv_19a4f12c8b3d4e5f",
    "status":         "processing",
    "poll_url":       "/api/status?task_id=dickpic_8c1b2f3e4d5a6b7c",
    "poll_interval":  3
  }
}

task_id is prefixed dickpic_ for production, dickpic_dryrun_ for sandbox. reservation_id uses the prefix rsv_ for normal submissions and res_dryrun_ for sandbox — informational only; the credit reservation becomes a confirmed charge when the analysis completes successfully.

Pre-preparing your image before sending reduces payload size and speeds up the overall round-trip — smaller images transfer faster, reach the analysis engine sooner, and you get results back quicker. The functions below produce an output that matches the analysis engine's expected input exactly, so there are no conversion delays on the way in.

Preparation algorithm

TARGET_PIXELS = 4_000_000   # 4 MP
TARGET_BYTES  = 2_250_000   # ~2.25 MB binary (fits ≤ 3 MB base64)
QUALITY       = 82

1. Load image, get width × height
2. If pixels > TARGET_PIXELS:
      scale = sqrt(TARGET_PIXELS / pixels)
      resize by scale
3. Re-encode as JPEG Q=82, strip Exif
4. If result > TARGET_BYTES:
      scale = sqrt(TARGET_BYTES / result_size)
      resize again, re-encode

# pip install Pillow
import base64, io, math
from PIL import Image

TARGET_PIXELS = 4_000_000
TARGET_BYTES  = 2_250_000
QUALITY       = 82

def prepare_image(path: str) -> str:
    img = Image.open(path).convert("RGB")
    w, h = img.size

    if w * h > TARGET_PIXELS:
        scale = math.sqrt(TARGET_PIXELS / (w * h))
        img = img.resize((int(w * scale), int(h * scale)), Image.LANCZOS)

    buf = io.BytesIO()
    img.save(buf, format="JPEG", quality=QUALITY, optimize=True)

    if buf.tell() > TARGET_BYTES:
        buf.seek(0)
        img2 = Image.open(buf).convert("RGB")
        scale = math.sqrt(TARGET_BYTES / buf.tell())
        w2, h2 = img2.size
        img2 = img2.resize((int(w2 * scale), int(h2 * scale)), Image.LANCZOS)
        buf = io.BytesIO()
        img2.save(buf, format="JPEG", quality=QUALITY, optimize=True)

    return base64.b64encode(buf.getvalue()).decode()

# Usage
payload = {"image": prepare_image("photo.jpg"), "prompt": {"language": "en"}}

// npm install sharp
const sharp = require('sharp');
const fs    = require('fs');

const TARGET_PIXELS = 4_000_000;
const TARGET_BYTES  = 2_250_000;

async function prepareImage(pathOrBuffer) {
    const src  = typeof pathOrBuffer === 'string' ? fs.readFileSync(pathOrBuffer) : pathOrBuffer;
    const meta = await sharp(src).metadata();
    const pixels = meta.width * meta.height;

    let pipeline = sharp(src).rotate();
    if (pixels > TARGET_PIXELS) {
        const scale = Math.sqrt(TARGET_PIXELS / pixels);
        pipeline = pipeline.resize(Math.round(meta.width * scale), Math.round(meta.height * scale), { fit: 'fill' });
    }

    let buf = await pipeline.jpeg({ quality: 82, mozjpeg: true }).withMetadata({}).toBuffer();

    if (buf.length > TARGET_BYTES) {
        const m2    = await sharp(buf).metadata();
        const scale = Math.sqrt(TARGET_BYTES / buf.length);
        buf = await sharp(buf)
            .resize(Math.round(m2.width * scale), Math.round(m2.height * scale))
            .jpeg({ quality: 82 })
            .toBuffer();
    }

    return buf.toString('base64');
}

// Usage
prepareImage('photo.jpg').then(image => {
    const payload = JSON.stringify({ image, prompt: { language: 'en' } });
});

<?php
// Requires GD (bundled with PHP)

const TARGET_PIXELS = 4_000_000;
const TARGET_BYTES  = 2_250_000;

function prepareImage(string $path): string
{
    [$w, $h, $type] = getimagesize($path);

    $src = match ($type) {
        IMAGETYPE_JPEG => imagecreatefromjpeg($path),
        IMAGETYPE_PNG  => imagecreatefrompng($path),
        IMAGETYPE_WEBP => imagecreatefromwebp($path),
        IMAGETYPE_GIF  => imagecreatefromgif($path),
        IMAGETYPE_BMP  => imagecreatefrombmp($path),
        default        => throw new \RuntimeException('Unsupported format'),
    };

    if ($w * $h > TARGET_PIXELS) {
        $scale   = sqrt(TARGET_PIXELS / ($w * $h));
        $nw      = (int)round($w * $scale);
        $nh      = (int)round($h * $scale);
        $resized = imagecreatetruecolor($nw, $nh);
        imagecopyresampled($resized, $src, 0,0, 0,0, $nw,$nh, $w,$h);
        imagedestroy($src);
        $src = $resized;
        $w = $nw; $h = $nh;
    }

    ob_start();
    imagejpeg($src, null, 82);  // GD strips Exif automatically
    $buf = ob_get_clean();
    imagedestroy($src);

    if (strlen($buf) > TARGET_BYTES) {
        $scale   = sqrt(TARGET_BYTES / strlen($buf));
        $src2    = imagecreatefromstring($buf);
        [$w2, $h2] = [imagesx($src2), imagesy($src2)];
        $nw      = (int)round($w2 * $scale);
        $nh      = (int)round($h2 * $scale);
        $resized = imagecreatetruecolor($nw, $nh);
        imagecopyresampled($resized, $src2, 0,0, 0,0, $nw,$nh, $w2,$h2);
        ob_start();
        imagejpeg($resized, null, 82);
        $buf = ob_get_clean();
        imagedestroy($src2);
        imagedestroy($resized);
    }

    return base64_encode($buf);
}

// Usage
$payload = json_encode(['image' => prepareImage('photo.jpg'), 'prompt' => ['language' => 'en']]);

Default Prompt Settings

Applied automatically for any field you omit:

{
  "mode":             "standard",
  "language":         "en",
  "focus":            "auto",
  "style_category":   "basic",
  "style":            "neutral_supportive",
  "intensity":        "medium",
  "humiliation_type": "general",
  "closer":           false,
  "humor":            false,
  "emoji":            false,
  "no_positive":      false
}

Override any subset. Example — Russian + playful tone:

{ "image": "...", "prompt": { "language": "ru", "style": "playful_teasing" } }

Prompt Parameters

Fields inside the prompt object control tone, language, focus, and intensity. See the Prompt Guide for descriptions and example outputs.

Returns the current task state. Five polling-channel statuses: processing, done, failed, expired, pdf_failed. The polling channel never returns status: "refused" — vision refusals surface here as status: "failed" with error_code: "VISION_REFUSAL"; the dedicated analysis.refused event lives in the webhook channel only. No Idempotency-Key needed (GET is naturally idempotent).

Common envelope

{
  "success": true,
  "data": {
    "task_id":      "dickpic_...",
    "status":       "processing | done | failed | expired | pdf_failed",
    "preview_path": null,
    "source_type":  "api_b2b"
  }
}

For api_b2b keys with status=done, the response is trimmed (no preview_path, no source_type, no pdf_url) — see the done example below. Fields created_at / updated_at are not returned (handler never emitted them).

status: done

{
  "data": {
    "status":      "done",
    "analysis":    { /* see Analysis Object below */ },
    "duration_ms": 4821
  }
}

duration_ms — model inference time (typically 4–12 seconds; max ~360 s). The api_b2b tier returns no pdf_url — this API is analysis-JSON only.

status: failed

{
  "data": {
    "status":        "failed",
    "error_code":    "VISION_REFUSAL | CORE_API_FAILED | IMAGE_PROCESSING_ERROR | VISION_NO_RESPONSE | VISION_INVALID_OUTPUT | ANALYSIS_FAILED",
    "error_message": "..."
  }
}

VISION_REFUSAL means the upstream model declined to analyse the image (content/quality reasons). Refused analyses do not consume a credit. Repeated refusals trigger temporary account blocks — see the Account Blocks section.

status: expired

{
  "data": {
    "status":        "expired",
    "error_code":    "AGGREGATION_TIMEOUT",
    "error_message": "Analysis timed out."
  }
}

Polling always returns AGGREGATION_TIMEOUT for expired tasks. The webhook channel uses the same code in analysis.expired.

status: pdf_failed

{
  "data": {
    "status":        "pdf_failed",
    "error_code":    "REPORT_GENERATION_FAILED"
  }
}

Not applicable to api_b2b — this tier never generates PDFs. Documented for completeness only.

Error response (success: false)

{ "success": false, "error": { "code": "TASK_NOT_FOUND", "message": "Task not found" } }

See the Error Codes section for the full list.

Cache-Control

• status=done → Cache-Control: private, max-age=3600 (terminal, safe to cache)
• All other statuses → no-cache, no-store, must-revalidate

Three gates protect the service from polling stampedes. The two 429 gates return a Retry-After header and error.retry_after_sec; the 410 hard cap does not — the polling window is permanently closed for that task and the server finalises it on its own.

Recommended client flow

1. POST /api/analyze (with Idempotency-Key)   → receive task_id
2. Wait 60 s  (180 s if webhook configured)
3. GET /api/status?task_id=...                every 3 s
4. status in {done, failed, expired, pdf_failed} → terminal, stop polling
5. Stop no later than 600 s after submit     — server enforces this

If the task is already in a terminal state when you poll, all three gates are bypassed — you get the result immediately. This lets a webhook receiver also fetch via polling as a fallback without hitting POLL_TOO_EARLY.

Structure of the analysis field returned when status = "done" — same shape via polling and via webhook. Flat JSON object with camelCase field names. All numeric ratings are integers in 0–10.

Detection flags

Anatomy ratings — integers 0–10

Photo quality ratings — integers 0–10

Computed aggregates — added by the API layer, not generated by the model

Narrative fields

Full example

{
  "dickVisibility":         true,
  "isDickFullyVisible":     true,
  "isDickMainObject":       true,
  "mainObjectDescription":  "dick",

  "lengthRating":           7,
  "girthRating":            8,
  "proportionalityRating":  9,
  "ballsRating":            6,
  "shapeRating":            8,
  "curveRating":            9,
  "headRating":             8,
  "skinRating":             7,
  "hygieneRating":          8,
  "veinsRating":            7,
  "groomingRating":         7,
  "hardnessRating":         9,
  "colorRating":            7,

  "lightingRating":         7,
  "focusRating":            8,
  "compositionRating":      7,
  "angleRating":            8,
  "distanceRating":         7,
  "backgroundRating":       6,
  "colorAccuracyRating":    7,

  "overall_score":          7.7,
  "image_quality_score":    7.1,

  "shortVerdict":           "Overall the image conveys confidence and clarity. The subject is well-framed and the lighting is flattering. A slight glare reduces color fidelity. Skin tone reads naturally. Minor background clutter could be cropped out.",
  "bestFeature":            "attractive curve with a well-defined glans",
  "keyStrengths":           ["expressive glans shape", "balanced proportions", "strong hardness"],
  "topPositiveFactors":     ["good lighting", "clean background", "natural angle"],
  "topLimitingFactors":     ["slight glare", "minor background clutter"],
  "photoImprovementTips":   ["reduce direct flash", "crop tighter on subject", "shoot from slightly lower angle"]
}

Degraded response (dickVisibility = false)

When the submitted image is not a valid anatomical subject (landscape, selfie without subject, non-human object, etc.) all rating fields are present but set to 0, aggregates to 0.0, and shortVerdict holds a user-facing explanation:

{
  "dickVisibility":         false,
  "isDickFullyVisible":     false,
  "isDickMainObject":       false,
  "mainObjectDescription":  "landscape photo",

  "lengthRating": 0, "girthRating": 0, "proportionalityRating": 0,
  "ballsRating":  0, "shapeRating": 0, "curveRating": 0,
  "headRating":   0, "skinRating":  0, "hygieneRating": 0,
  "veinsRating":  0, "groomingRating": 0, "hardnessRating": 0, "colorRating": 0,

  "lightingRating": 0, "focusRating": 0, "compositionRating": 0,
  "angleRating":    0, "distanceRating": 0, "backgroundRating": 0, "colorAccuracyRating": 0,

  "overall_score":          0.0,
  "image_quality_score":    0.0,

  "shortVerdict":           "The image doesn't show anatomical content in a way I can analyze. Please resubmit a clearer photo of the intended subject.",
  "bestFeature":            "",
  "keyStrengths":           [],
  "topPositiveFactors":     [],
  "topLimitingFactors":     [],
  "photoImprovementTips":   []
}

Tip: to display on a 0–100 scale, compute round(overall_score * 10) client-side.

Text fields vary based on prompt.language, prompt.style, and prompt.intensity. Scores are deterministic for the same image regardless of prompt.

Unauthenticated. No X-API-Key required. No rate limit.

Response — always HTTP 200

{ "status": "ok" }

or, when degraded:

{
  "status":  "degraded",
  "message": "Analysis queue is experiencing delays. New requests are accepted but may take longer than usual."
}

The body is intentionally minimal. Internal component details (database, Redis, worker counts, Core API state) are not exposed — clients don't need to know how the system is structured. For deeper observability, use the admin panel.

Recommended uses

• External uptime probes (UptimeRobot, StatusCake, Pingdom) — probe every 30–60 s, alert on status != "ok" or non-200 transport failure.
• Pre-flight before long-running batch submissions — if degraded, consider waiting or reducing concurrency.

⚠ Do not use as keepalive or per-request health check — the endpoint performs live DB / Redis / Core probes on every call. Poll at most once per 30 seconds.

Webhooks are the preferred delivery mechanism for production. They eliminate polling traffic, avoid 429 rate-limit issues, and deliver results with lower latency. Pattern: webhook + fallback poll after 180 s of silence.

Configuration

Per-key at /api-tool/keys:

• Webhook URL — HTTPS required, must accept POST with Content-Type: application/json.
• Webhook secret — 64 hex chars (32 random bytes). Shown once on creation/rotation. Used for HMAC signing.

Changes take effect immediately for new events; in-flight deliveries continue with the previous configuration.

Event types

Payload — analysis.completed

{
  "event":        "analysis.completed",
  "event_id":     "evt_dickpic_abc123_completed",
  "delivery_id":  "8f0c4a2e-1d3b-4f5a-9c6e-7b8a1d2f3e4c",
  "task_id":      "dickpic_abc123",
  "timestamp":    "2026-04-20T12:35:10+00:00",
  "status":       "done",
  "analysis":     { /* see Analysis Object */ },
  "duration_ms":  4821
}

event_id is the stable identifier (format evt_<task_id>_<event_short>) — same value across retries of the same event; dedupe by this field. delivery_id is per-attempt (UUID v4, changes on retry) — not suitable for dedup. timestamp is ISO 8601, set to the task's finished_at. Fields account_id and is_dry_run are not emitted (webhook is already scoped to one account by the secret; dry-run is identifiable by task_id prefix).

Signing — 4 headers on every delivery

Verification (Python)

import hmac, hashlib, time

def verify(headers, raw_body, secret):
    received  = headers.get("X-DPP-Signature", "")
    timestamp = headers.get("X-DPP-Timestamp", "")
    if not received or not timestamp:
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False  # replay-protection window
    message  = f"{timestamp}.".encode() + raw_body   # raw_body = exact bytes, not re-encoded
    expected = "sha256=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(received, expected)

Use a constant-time compare (hmac.compare_digest in Python, crypto.timingSafeEqual in Node). See llms.txt § 18 for full Node.js / Flask receivers.

Retry & delivery guarantees

• Timeout: 10 s per delivery attempt
• Retry schedule: 0 s (immediate), 30 s, 180 s — 3 attempts total
• Success: HTTP 2xx within 10 s. Non-2xx, timeout, or connection error → retry
• Auto-disable: 10 failed deliveries and a failure streak lasting ≥ 15 min — both conditions required. A short burst (e.g. DNS outage that resolves in 30 s) will not trip auto-disable. Shown in the Keys dashboard. Fix and re-enable manually.
• At-least-once delivery — dedupe by event_id (format evt_<task_id>_<event_short>, stable across retries). Do not dedupe by delivery_id — it changes per attempt.
• No ordering guarantee — concurrent tasks may produce webhooks in any order.
• Max payload size: 512 KB.

Test integration end-to-end without purchasing a Simple Pack or Production Contract. Add "dry_run": true to the POST body.

Server behavior when dry_run=true

• No credit reservation, no upstream analysis call
• image field is optional (ignored if provided)
• Returns a synthetic task_id prefixed dickpic_dryrun_ and a reservation_id prefixed res_dryrun_
• After ~10 s, background worker transitions the task to done with a fixed mock analysis (structure byte-for-byte identical to production; text fields marked [DRY-RUN MOCK])
• GET /api/status polling works exactly like production
• Webhooks are not delivered for dry-run tasks. Sandbox is poll-only — even if you have a webhook configured, no analysis.completed push fires for dickpic_dryrun_ tasks. Test webhook signing with the manual "Send test ping" button in the Keys dashboard.

Response — 202 Accepted

{
  "success": true,
  "data": {
    "task_id":                  "dickpic_dryrun_a1b2c3d4e5f6a7b8c9d0e1f2",
    "reservation_id":           "res_dryrun_...",
    "status":                   "processing",
    "poll_url":                 "/api/status?task_id=dickpic_dryrun_...",
    "poll_interval":            3,
    "dry_run":                  true,
    "dry_run_remaining":        97,
    "dry_run_delivery_eta_sec": 10
  }
}

Hard limits

• 100 requests per account, lifetime. Counter never resets. Not extensible under any circumstances. Exhausted → 403 DRY_RUN_QUOTA_EXCEEDED.
• 100 requests per hour rate cap, separate from per-key preset limits. Exceeded → 429 DRY_RUN_RATE_EXCEEDED with Retry-After.

Each API key has a rate-limit preset chosen at creation time. Excess → 429 RATE_LIMIT_EXCEEDED with error.retry_after_sec + Retry-After header.

There are no X-RateLimit-* response headers. Track rate limits on your side from the 429 error.retry_after_sec field.

Repeated vision refusals trigger a progressive temporary block. This prevents abuse of the free-retry policy (refused analyses do not consume a credit). The counter is for consecutive refusals — a single successful done resets it to zero, and the counter also resets if the last refusal is older than 24 h (sliding staleness window).

Response while blocked (HTTP 403)

{
  "success": false,
  "error": {
    "code":            "ACCOUNT_TEMPORARILY_BLOCKED",
    "message":         "Account temporarily blocked after repeated analysis failures. ...",
    "blocked_until":   "2026-04-20T13:00:00Z",
    "block_reason":    "consec_refusals_1h | consec_refusals_24h | consec_refusals_manual",
    "retry_after_sec": 3600
  }
}

All three escalation levels use the same HTTP code (403) and the same error code (ACCOUNT_TEMPORARILY_BLOCKED) — block_reason tells you which level. For the manual level, blocked_until is effectively far-future. Manual-policy blocks (set by support, unrelated to refusal escalation) use a different code: ACCOUNT_BLOCKED and do not carry blocked_until.