Caption API with real slang

Generate captions in the slang of Ecuador, Argentina, Colombia and Peru from your own server. Same engine and price as the web app: 1 credit per generation of 3 captions, 1.5 if you also ask for an English translation.

Authentication

Create a key in the app, in the API tab of your account (/en/app). Send it with every request using one of these headers:

Authorization: Bearer psq_...
X-API-Key: psq_...
  • The key is shown only once, when you create it: store it somewhere safe.
  • You can revoke it at any time from the same screen.
  • Up to 5 active keys per account.
  • Limit: 60 requests per minute per key.

Never expose your key in browser code (React, Vue, mobile apps, etc.). Anyone could copy it and spend your credits. Call the API from your server and keep the key in an environment variable.

Base URL: https://api.pesquisidor.com/api/v1

Generate captions

POST/v1/generate

JSON body:

FieldTypeDescription
countryCode"EC" | "AR" | "CO" | "PE"Required. Country whose slang is used.
platform"tiktok" | "instagram" | "other"Optional. Defaults to "other".
postDescriptionstringRequired. 1 to 500 characters: what your post is about.
tonestringOptional. Up to 40 characters (e.g. "divertido").
translateTo"en"Optional. "en" also returns a natural English translation of each caption in translations (+0.5 credit). If the translation can't be produced you still get the captions, translationFailed: true, and the surcharge is refunded.

200 response: three captions (in the country's Spanish), the slang terms used (with meaning and register), the translations if requested, the cost charged and your remaining balance.

{
  "id": 1234,
  "captions": ["…", "…", "…"],
  "slang": [
    { "term": "…", "meaning": "…", "register": "casual" }
  ],
  "translations": ["…", "…", "…"],
  "cost": 1.5,
  "creditsRemaining": 41.5
}

Check your balance

GET/v1/me
{
  "credits": {
    "balance": 41.5,
    "costPerGeneration": 1,
    "translationSurcharge": 0.5
  }
}

Available countries

GET/v1/countries
[
  { "code": "EC", "name": "Ecuador", "language": "es" },
  …
]

Errors

Errors respond with JSON containing an error field:

HTTPerrorMeaning
400validation_failedThe body is invalid. Includes details listing the fields that failed.
401invalid_api_keyThe key is missing, wrong or revoked.
402insufficient_creditsNot enough credits. Includes balance and cost.
429too_many_requestsYou exceeded 60 requests per minute with that key.
502generation_failedGeneration failed. Credits are refunded automatically.
{ "error": "insufficient_credits", "balance": 0.5, "cost": 1 }

Examples

curl

curl -X POST https://api.pesquisidor.com/api/v1/generate \
  -H "Authorization: Bearer $PESQUISIDOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "countryCode": "EC",
    "platform": "instagram",
    "postDescription": "Sunset photo at the beach with my friends",
    "tone": "divertido",
    "translateTo": "en"
  }'

JavaScript (fetch)

// Node.js 18+ (server side). Never put the key in browser code.
const res = await fetch("https://api.pesquisidor.com/api/v1/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PESQUISIDOR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    countryCode: "AR",
    platform: "tiktok",
    postDescription: "Video trying the new coffee shop in the neighborhood",
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}`);
console.log(data.captions, data.creditsRemaining);

Python (requests)

import os
import requests

res = requests.post(
    "https://api.pesquisidor.com/api/v1/generate",
    headers={"X-API-Key": os.environ["PESQUISIDOR_API_KEY"]},
    json={
        "countryCode": "CO",
        "platform": "other",
        "postDescription": "Launching my new t-shirt collection",
        "translateTo": "en",
    },
    timeout=30,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data.get('error')}")
print(data["captions"], data.get("translations"), data["creditsRemaining"])

Pricing

Each generation costs 1 credit, same as on the web, and 1.5 with translateTo. Credits are shared with your account: check your balance in the app or with GET /v1/me. If a generation fails (502), credits are refunded automatically.

Create an account and API keyTry the demo