Duowenwen

API & Agent

Let a script or an AI agent send in a question and fetch the reference answer and explanation. Credits work exactly as they do on the website.

Two ways to authenticate

API key (APIKEY): after you sign in, create one on the API & Agent page. It is shown only once and you can revoke it any time. Best for your own scripts.

AIBOT: an agent identity. The agent exchanges its own long-lived key for a short-lived token with our sign-in service, then calls this API with it. Everything it uses is charged to the agent owner's credits. An admin has to give the agent the dww:user capability.

Never put credentials in a query string, a repo, logs or a chat. Machine-readable versions: /.well-known/agent-skill · OpenAPI

Endpoints

Always send Authorization: Bearer <credential>. Scopes: homework:write, homework:read, credits:read, credits:redeem.

POST /api/v1/homework: send a question. Either the raw bytes of one image, or a multipart body with 1 to 9 image files and an optional note. Returns a job_id.

curl -sS -X POST https://duowenwen.ai/api/v1/homework \
  -H "Authorization: Bearer $DUOWENWEN_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @question.jpg

GET /api/v1/homework/{id}: status, reference answer, explanation and the model receipt. Poll every 3 to 5 seconds until it is done or failed.

curl -sS https://duowenwen.ai/api/v1/homework/<job_id> \
  -H "Authorization: Bearer $DUOWENWEN_API_KEY"

GET /api/v1/credits: your balance, prices and recent activity.

curl -sS https://duowenwen.ai/api/v1/credits \
  -H "Authorization: Bearer $DUOWENWEN_API_KEY"

POST /api/v1/redeem: turn a redeem code into credits.

curl -sS -X POST https://duowenwen.ai/api/v1/redeem \
  -H "Authorization: Bearer $DUOWENWEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"DWW-XXXX-XXXX-XXXX-XXXX"}'

Credits and errors

One submission with 1 to 3 photos uses 60 credits, 4 to 6 photos 90, and 7 to 9 photos 120 (fast mode: 40, 60 and 80). If we can't produce the explanation, the credits are returned automatically. If your balance is too low you get a 402 with required_credits and balance, and nothing is charged.

Other codes: 401 means the credential is missing or revoked, 403 a missing scope, 409 that the account owner hasn't accepted the terms on the website yet, and 429 that you are going too fast (see Retry-After). The default limit is 60 requests per minute per credential.

Photos and answers are kept for the same time as on the website, then deleted. They are not used to train our own models.