Quick Start

Get up and running with API-key auth, generation, job polling, and publishing.

1. Authenticate

Every API request uses a bearer token.

export WONDA_API_KEY="sk_your_api_key_here"
export WONDA_API_BASE="https://api.wondercat.ai/api/v1"

If you are using the CLI for local editing or scripting, install it and sign in:

npm i -g @degausai/wonda
wonda auth login
wonda auth check

2. Generate an image

Submit a direct generation request. The response contains an inferenceJobId.

curl -X POST "$WONDA_API_BASE/image/generate" \
  -H "Authorization: Bearer $WONDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A polished product shot of a ceramic mug on travertine",
    "params": {
      "aspectRatio": "1:1",
      "resolution": "1K"
    }
  }'
{
  "inferenceJobId": "019e1b6c-e954-89d3-bcef-6608093508e5"
}

3. Poll the inference job

Poll until the status is succeeded or failed. A succeeded image job includes output media records.

curl "$WONDA_API_BASE/jobs/inference/019e1b6c-e954-89d3-bcef-6608093508e5" \
  -H "Authorization: Bearer $WONDA_API_KEY"
{
  "inferenceJobId": "019e1b6c-e954-89d3-bcef-6608093508e5",
  "model": "nano-banana-2",
  "provider": "runware",
  "type": "image",
  "prompt": "A polished product shot of a ceramic mug on travertine",
  "status": "succeeded",
  "params": {
    "aspectRatio": "1:1",
    "resolution": "1K"
  },
  "errorCode": null,
  "errorMessage": null,
  "infoMessage": null,
  "createdAt": "2026-06-12T12:00:00.000Z",
  "finishedAt": "2026-06-12T12:00:12.000Z",
  "outputs": [
    {
      "inferenceJobOutputId": "019e1b6f-5e8d-88c2-a0f3-159684318a10",
      "outputKey": "image",
      "outputValue": null,
      "createdAt": "2026-06-12T12:00:12.000Z",
      "media": {
        "mediaId": "019e1b70-6f9e-80fd-8c49-690bcbdaf8db",
        "url": "https://storage.googleapis.com/...",
        "mimeType": "image/png",
        "width": 1024,
        "height": 1024,
        "durationMs": null,
        "fps": null
      }
    }
  ],
  "attachments": []
}

Use the output media.mediaId as the input to publishing or local CLI editing.

4. Publish to Instagram

Get an instagramAccountId from GET /instagram/accounts, then create a publish job.

curl -X POST "$WONDA_API_BASE/publish/instagram" \
  -H "Authorization: Bearer $WONDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "019e1b70-6f9e-80fd-8c49-690bcbdaf8db",
    "instagramAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "caption": "Made with Wonda",
    "product": "IMAGE"
  }'
{
  "outputJobId": "019e1b76-74d7-8c7e-a927-6bd34bfaa114",
  "status": "queued"
}

Poll the publish job until it reaches a terminal status.

curl "$WONDA_API_BASE/jobs/publish/019e1b76-74d7-8c7e-a927-6bd34bfaa114" \
  -H "Authorization: Bearer $WONDA_API_KEY"

Next steps