API Testing with Postman
A ready-to-use Postman collection for the Doppl API. Import it into Postman or any compatible client (Insomnia, Bruno, Hoppscotch), set your credentials, and walk through authentication, avatar generation, webhook delivery, and status polling without writing a line of code.
{{variable}} references. Test scripts auto-save new keys and avatar IDs into the environment, so each request chain flows into the next.
Endpoints in the collection
Every public endpoint in v1, organized so a single click walks you from a fresh demo key to a generated avatar.
- POST /api/v1/keys
- Mint a free demo key (auth)
- GET /oauth/authorize
- POST /oauth/token
- POST /oauth/token
- OAuth 2.0 authorization & token exchange (auth)
- GET /api/v1/styles
- POST /api/v1/avatars
- POST /api/v1/avatars
- GET /api/v1
- Avatar generation
- GET /api/v1/avatars/:id
- GET /api/v1/avatars
- GET /api/v1/stats
- Status polling
Import & run the collection
Postman reads v2.1 schema .json files natively — no transcoding required.
1. Import both files
In Postman, click Import → Upload Files and select both JSON files you downloaded above. The collection lands under the Doppl API name; the environment appears in the top-right environment picker as Doppl API.
2. Pick the environment
In the top-right of Postman, select Doppl API from the environment dropdown. Every {{variable}} now resolves against the file you imported.
3. Send the demo-key request
Open 1. Authentication → Generate Demo API Key and hit Send. The test script writes the returned api_key straight into the environment, so every following request picks it up.
POST /api/v1/keys mints a free demo key on the fly (5 requests/minute). If you already have a real key, replace api_key in the environment with your dppl_… string and skip step 3.
4. Generate and poll
Open 2. Avatar Generation → Create Avatar (Synchronous), set photo_url in the environment to any public HTTPS image of a face, and send. The test script saves the new id to last_avatar_id. Now open 3. Status Polling → Get Avatar by ID — the URL is pre-built with {{last_avatar_id}} — and send. Re-send until status reads completed.
HTTP 429. Either wait, mint a new key, or replace api_key in the environment with a production key.
Environment variables
The environment file ships with these placeholders. Fill in the blanks you need; the rest are pre-populated with sensible defaults.
| Variable | Default / Purpose | When to set |
|---|---|---|
| base_url | https://doppl.polsia.app/api/v1 | Use the production URL. Switch to a localhost port for local dev. |
| auth_url | https://doppl.polsia.app/oauth | Rarely changed. Override only for a custom OAuth host. |
| api_key | (secret) | Auto-filled by the demo-key request, or paste your own dppl_… key. |
| key_name | My Postman Workspace | Sent as the name when minting a demo key. |
| user_email | (blank) | Optional. If set, the demo key is linked to this email for dashboard access. |
| photo_url | https://example.com/sample-photo.jpg | Replace with any public HTTPS image of a face before generating an avatar. |
| avatar_style | stylized | One of: stylized, realistic, anime, pixel, clay, minimal. |
| webhook_url | (blank) | If set, the Create Avatar with Webhook request fires a POST here on completion. |
| oauth_client_id | (blank) | Issued when you register your OAuth app. |
| oauth_client_secret | (secret) | Issued alongside client_id. Keep this secret. |
| oauth_redirect_uri | https://localhost/callback | Must match the URI registered for your OAuth app. |
| oauth_scope | avatars:read avatars:write | Space-separated scopes for the authorization request. |
| oauth_auth_code | (blank) | Paste the ?code=… value from the OAuth redirect. |
| oauth_access_token | (secret) | Auto-saved by the token-exchange test script. |
| oauth_refresh_token | (secret) | Auto-saved by the token-exchange test script; reuse to mint new access tokens. |
| last_avatar_id | (auto) | Auto-filled by the create-avatar test scripts. |
| completed_avatar_url | (auto) | Auto-filled the first time a poll returns status: "completed". |