Tuqu Photo API

Overview

Use this skill to call the Dream Weaver APIs safely and consistently across both hosts: https://photo.tuqu.ai for image and catalog flows, and https://billing.tuqu.ai/dream-weaver for recharge flows. The main failure mode is choosing the wrong host or authentication mode: body userKey for /api/billing/balance and all v2 generation endpoints, header x-api-key for character management and history APIs, Authorization: Bearer <serviceKey> for recharge endpoints, and no auth for discovery and prompt enhancement. serviceKey and userKey refer to the same credential.

Set Base URLs Only

Set these only when overriding the defaults:

• TUQU_BASE_URL=https://photo.tuqu.ai
• TUQU_BILLING_BASE_URL=https://billing.tuqu.ai/dream-weaver

Do not rely on a shared credential environment variable. The agent must provide the credential explicitly on every authenticated request so multiple roles can use different service keys safely.

Prefer scripts/tuqu_request.py over ad-hoc curl so host selection, auth, and JSON handling stay consistent.

Choose the Endpoint

Follow this decision flow:

1. Need available presets, template IDs, style IDs, or usage hints? Call /api/catalog.
2. Need direct text or reference-image generation without preset logic? Optionally call /api/enhance-prompt, then call /api/v2/generate-image.
3. Need template or style generation from a preset ID? Call /api/catalog first, prepare at least one source image, then call /api/v2/apply-preset.
4. Need persistent characters or multi-character scene generation? Use /api/characters, optionally call /api/enhance-prompt, then call /api/v2/generate-for-character.
5. Need prior outputs or audit trail data? Use /api/history.
6. Need pricing or remaining credits? Use /api/model-costs and /api/billing/balance.
7. Need to top up a project's balance? Call /api/v1/recharge/plans, then /api/v1/recharge/wechat or /api/v1/recharge/stripe.

Read references/endpoints.md for exact request and response fields. Read references/workflows.md for end-to-end task recipes.

Follow Operating Rules

• Verify the auth mode before every request. Even when the same credential backs multiple endpoints, /api/v2/generate-for-character still requires body userKey, /api/characters and /api/history still require x-api-key, and recharge endpoints still require bearer auth.
• Verify the host before every request. Recharge endpoints live on TUQU_BILLING_BASE_URL, not TUQU_BASE_URL.
• Provide the credential explicitly on every authenticated helper call with --service-key <role-service-key>, unless the workflow explicitly requires you to place it in the JSON body or query string.
• Send JSON with Content-Type: application/json.
• Send base64 images as full data URLs such as data:image/jpeg;base64,..., not raw base64 fragments.
• Treat /api/catalog as the source of truth for presetId, preset type, and variable names. Do not guess placeholders.
• For /api/v2/apply-preset, send at least one sourceImages or sourceImageUrls entry. Template presets treat them as face-reference images; style presets treat the first one as the image to transform.
• Use /api/model-costs before overriding modelId on cost-sensitive jobs.
• Use ratio: "Original" only when at least one reference image is present, because the server measures the first reference image.
• Prefer Authorization: Bearer <serviceKey> for recharge endpoints. Use query or body fallback only when the caller cannot set headers.
• Preserve imageUrl, promptUsed, model, remainingBalance, transactionId, and historyItem when the API returns them.
• Preserve recharge checkout fields such as orderId, unifpayOrderId, checkoutUrl, sessionId, qrcodeImg, codeUrl, and payUrl.
• Surface API error codes directly, especially INVALID_REQUEST, UNAUTHORIZED, NOT_FOUND, INSUFFICIENT_BALANCE, GENERATION_FAILED, PAYMENT_NOT_CONFIGURED, and CURRENCY_NOT_SUPPORTED.

Use the Request Helper

Use the helper for repeatable API calls:

python3 scripts/tuqu_request.py GET /api/catalog --query type=all
python3 scripts/tuqu_request.py GET /api/model-costs
python3 scripts/tuqu_request.py POST /api/enhance-prompt \
  --json '{"category":"portrait","prompt":"soft editorial portrait with window light"}'
python3 scripts/tuqu_request.py POST /api/v2/generate-image \
  --service-key <role-service-key> \
  --body-file payloads/generate-image.json
python3 scripts/tuqu_request.py GET /api/v1/recharge/plans \
  --service-key <role-service-key>
python3 scripts/tuqu_request.py POST /api/v1/recharge/stripe \
  --service-key <role-service-key> \
  --json '{"planId":"698b7fead4c733c85f2a9c74","successUrl":"https://your-app.com/payment/success","cancelUrl":"https://your-app.com/payment/cancel"}'

The helper auto-detects both host and auth for the supported endpoints in this skill. Pass --service-key on every authenticated call. Override with --base-url or --auth-mode only when you have a documented reason.

Handle Common Tasks

Generate from prompt or references

1. Optionally call /api/enhance-prompt when the user prompt is vague.
2. Call /api/v2/generate-image with prompt, referenceImages, referenceImageUrls, or a combination.
3. Return the imageUrl and any balance or transaction metadata.

Generate from a preset

1. Call /api/catalog and pick a valid preset.
2. Inspect whether the preset is a template or a style.
3. Provide at least one sourceImages or sourceImageUrls entry.
4. Fill variableValues only with the preset's defined placeholders.
5. Call /api/v2/apply-preset.

Generate with saved characters

1. Create or look up characters through /api/characters.
2. Optionally enhance the scene prompt with /api/enhance-prompt.
3. Call /api/v2/generate-for-character.
4. Save or expose the returned historyItem when present.

Inspect balance and history

1. Call /api/billing/balance before expensive jobs when the user asks about credits.
2. Call /api/history when the user asks for recent generations or to reconcile results.

Recharge with WeChat or Stripe

1. Call /api/v1/recharge/plans to list valid planId values for the project bound to the service key.
2. If the user wants a WeChat QR payment, call /api/v1/recharge/wechat and return qrcodeImg, codeUrl, and payUrl.
3. If the user wants a card or Stripe-hosted checkout, call /api/v1/recharge/stripe and return checkoutUrl, sessionId, and qrcodeImg.
4. Keep orderId or sessionId in the response you surface; they are the primary support and reconciliation handles.

Recover from Failures

• On INSUFFICIENT_BALANCE, stop and report the remaining balance if available.
• On INVALID_REQUEST, compare the payload against references/endpoints.md and call out the missing field explicitly.
• On NOT_FOUND from /api/v2/apply-preset, re-run /api/catalog; the presetId is wrong or no longer active.
• On UNAUTHORIZED, verify whether the endpoint expects body userKey, header x-api-key, or bearer serviceKey, and verify that the caller supplied the intended role-specific credential.
• On recharge UNAUTHORIZED, verify the service key has not been revoked or frozen and that you are sending it to the billing host.
• On PAYMENT_NOT_CONFIGURED, report which channel is missing at the project or global config layer.
• On CURRENCY_NOT_SUPPORTED, stop and explain that WeChat only supports direct CNY or JPY, plus USD via project FX conversion.
• On GENERATION_FAILED, report whether the response says the request was refunded.