Developer docs

AI WORKSHOP runs the OpenAI-compatible relay API behind the Parrot AI desktop app and third-party clients: chat, image generation, asynchronous video and 3D, embeddings and a model catalogue, all billed in credits. The base URL ishttps://parrot.amorist.cn/v1.

Every /v1 request must be authenticated: send theAuthorization: Bearer <token> request header, with a token minted byPOST /api/auth/login(phone number + password). In the browser, a web session or thedsh_tokencookie works too. Unauthenticated requests get 401.

Billing runs on credits: each call deducts from your balance by model and usage, itemised in the account centre. A short balance returns 402; a rate-limited call returns 429.

• POST /api/auth/registerPhone number + password

  Sign up and you can sign in right away. An invite code is optional.

• POST /api/auth/loginReturns a Bearer JWT

  Desktop apps and third-party clients use it to obtain a /v1 access token.

• POST /api/auth/refreshRenewal

  Refresh once a token expires, without signing in again.

Payment results arrive as a server-to-server notification:POST https://parrot.amorist.cn/api/payment/alipay/notify. The notification carries an Alipay signature, and orders and credited balances only move once the server has verified it. Never trust a payment callback whose signature was not checked.

Every /v1 response carries RFC 9218 rate-limit headers:RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset(600 requests/minute per user and 240 per IP by default, both adjustable through deployment environment variables). A limited request returns 429 with aRetry-Aftervalue in seconds.

The major version lives in the URL path (currently /v1). When a new major version ships, the old one stays in service for at least 12 months. A deprecated endpoint carries aDeprecationresponse header and is announced here, through theSunsetheader, at least 30 days before it is switched off. Integrate against those two headers rather than discovering the migration at 404/410.

Data capabilities (social content, reviews and reputation, e-commerce products, web search, captcha solving, email, SMS receiving, IP proxies, AI interfaces) are a separate line from the /v1 relay: over there models, over here data. Each line carries its own quota, but the data serviceneeds only one credential, shared by REST and MCP.

Credentials are issued in the console under “Integrations & credentials → API Keys” (they look likeparrot_…). You can scope one to a few families of capability, you cangive that key its own quota(daily / monthly / lifetime caps on credits and calls — once it is spent, that key is refused and every other key keeps working), and you can rotate or revoke it at any time. Every request carries the same header:Authorization: Bearer parrot_…

MCP follows the standard protocol(Streamable HTTP): the endpoint isPOST https://parrot.amorist.cn/mcp. Handshake, tool list and calls are all standard MCP, andthat page in the consolegives a config you can paste straight in, per client (Claude Code / Cursor / ChatGPT / generic). Six tools are exposed today: list capabilities, read a capability's parameter table, call a capability, query an async job,wait for an async job to finish, and read usage.

Responses arrive over anSSE stream(text/event-stream), so the server canpush progress on its own: pass_meta.progressTokenin the request and you will receivenotifications/progress. For an asynchronous capability,data_wait_joblets the server wait for the job inside this same call (progress pushed by the server, the result row arriving with the final response), so the client never has to poll round after round. Polling and waiting are not billed. A client that only accepts a single JSON response should setAccepttoapplication/json, text/event-stream.

CallGET /api/data/usageor MCP'sdata_get_usagewith a key and the response also carries that key's quota reading (the cap and what this window has used), so a program can work out how many calls it has left.

{
  "mcpServers": {
    "parrot-data": {
      "type": "http",
      "url": "https://parrot.amorist.cn/mcp",
      "headers": {
        "Authorization": "Bearer parrot_…"
      }
    }
  }
}