Your workflow.
The SHOUD API.

Active paid Max 5×, Max 20× and Business plans include server API access. Tasks share your workspace credits and concurrency. Trial access does not include API calls.

Choose a plan ↗ Manage keys in the app

Create a server key

After verified paid activation, open Developer API in the workspace. The key is shown once. Store it in your server’s secret storage. Never embed it in browser code, a mobile app, a URL or a repository. Revoke compromised keys immediately.

Preview before spending

curl https://app.shoud.online/api/v1/tasks
  -H "Authorization: Bearer YOUR_SERVER_KEY"
  -H "Content-Type: application/json"
  -d '{"prompt":"Draft a concise event checklist","model":"gemini-3.8-flash","kind":"document","preview":true}'

Join the curl lines with shell continuation characters appropriate to your terminal. A preview returns estimatedCredits without starting a model request or deducting credits.

Submit an approved task

Use preview:false and set max_credits to at least the current estimate. Include an Idempotency-Key header with 8–128 letters, numbers, underscores or hyphens. Repeating identical JSON with the same key returns the known original result. If an outcome is pending or uncertain, 409 prevents a duplicate request; do not bypass it with another key.

{"prompt":"Draft a concise checklist","model":"gemini-3.8-flash","kind":"document","preview":false,"max_credits":250}

The example budget is illustrative: use the real estimate. Creation returns HTTP 202 with taskId and reservedCredits.

Endpoints

Method	Path	Result
GET	/api/v1/models	Integrated model choices
POST	/api/v1/tasks	Preview or create a task
GET	/api/v1/tasks/{taskId}	Status, response, credits and file metadata
GET	/api/v1/tasks/{taskId}/files/{index}	Short-lived signed download URL

Supported inputs and outputs

A text prompt up to 12,000 characters, with a JSON request up to 16 KB. Kinds: auto, chat, research, document, pdf, slides, spreadsheet, code, image and video. Request a compatible model and task type. This API version does not accept file uploads, attachment paths, project IDs or conversation references. Use it from your backend; browser CORS access is not supported.

Image generation uses Nano Banana 2.1 and reserves 100 credits. Video uses Veo 3.1 Fast and reserves 400 credits for one four-second 720p silent clip, with people generation disabled. Both currently accept text prompts only. Text tasks reserve a model-specific budget and settle known usage. Failed or cancelled provider requests can consume usage; uncertain outcomes can retain the approved reservation. Running out of credits never causes an early card charge.

Errors and limits

401: invalid or revoked key.
403: paid entitlement or API-enabled plan required.
404: endpoint or owned task not found.
409: idempotency conflict, pending request or outcome requiring review.
429: rate, credit or concurrency limit reached.

Use backoff for reads. Do not blindly repeat task creation. API keys can authorize credit-consuming work on their owner’s account. Ownership and paid access are enforced; only hashes of keys are stored server-side. No SSO, dedicated tenancy, zero retention or uptime SLA is implied.

Privacy · Credit policy · Security · Model Garden