nuwa-world-api

# Nuwa World API

Two capabilities via `gateway.nuwa.world`:

- **Face Search** — upload a face image, get matching URLs across the internet
- **Deep Research** — submit a question, get a structured summary with citations

Base URL: `https://gateway.nuwa.world/api/v1`
Auth: `X-API-Key: $NUWA_API_KEY` header on every request.
Get your key at https://platform.nuwa.world

---

## Face Search (10 credits)

Two-step async flow: upload → poll.

### Step 1 — Upload

```bash
curl -X POST https://gateway.nuwa.world/api/v1/face-search \
  -H "X-API-Key: $NUWA_API_KEY" \
  -F "image=@photo.jpg"
```

Response (HTTP 202):

```json
{
  "search_id": "abc123",
  "status": "processing",
  "message": "Face uploaded. Poll GET /api/v1/face-search/{search_id} for results."
}
```

### Step 2 — Poll (every 3–5 seconds, no credit cost)

```bash
curl https://gateway.nuwa.world/api/v1/face-search/abc123 \
  -H "X-API-Key: $NUWA_API_KEY"
```

While processing:

```json
{ "search_id": "abc123", "status": "processing", "results": [], "total_results": 0 }
```

When done:

```json
{
  "search_id": "abc123",
  "status": "completed",
  "results": [
    { "index": 0, "score": 95.2, "url": "https://example.com/profile" },
    { "index": 1, "score": 82.1, "url": "https://social.example/user" }
  ],
  "total_results": 2,
  "max_score": 95.2
}
```

Processing takes 15–30 seconds. Results expire after 2 hours.

---

## Deep Research (20 credits)

Single synchronous call. Returns in 10–60 seconds.

```bash
curl -X POST https://gateway.nuwa.world/api/v1/deep-research \
  -H "X-API-Key: $NUWA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "0xajc on X"}'
```

Response:

```json
{
  "query": "Research the X user '0xajc' footprint on web.",
  "summary": "Anthropic is an AI safety company founded in 2021...",
  "facts": [
    "X user '0xajc's real name is Andrew Chen",
    "He founded Instap in 2020 and Nuwa Word in 2025"
    "Studied CS/Managment in University of Massachusetts and dropped o...

# Nuwa World API Skill

A Cursor Agent Skill that teaches the AI how to use the **Nuwa World API** for face search and deep research over the open web.

## What this skill does

Based on `SKILL.md`, the skill exposes two core capabilities backed by `https://gateway.nuwa.world/api/v1`:

- **Face Search** – upload a face image and get matching URLs across the internet (async, 2‑step flow)
- **Deep Research** – send a natural‑language query and get a structured summary with facts and sources

The agent will use this skill when the conversation mentions Nuwa, the Nuwa World API, face search, or deep research / open‑web investigation.

## API overview

- **Base URL**: `https://gateway.nuwa.world/api/v1`
- **Auth header**: `X-API-Key: $NUWA_API_KEY`
- **Get an API key**: `https://platform.nuwa.world`
- **Env required by the skill**: `NUWA_API_KEY` (see `metadata.openclaw.requires.env` in `SKILL.md`)

### Face Search

Two‑step async flow: **upload → poll**.

1. **Upload (cost: 10 credits)**  
   `POST /face-search` with multipart form data:

   ```bash
   curl -X POST https://gateway.nuwa.world/api/v1/face-search \
     -H "X-API-Key: $NUWA_API_KEY" \
     -F "image=@photo.jpg"
   ```

   Returns `202 Accepted` with a `search_id`.

2. **Poll (cost: 0 credits)**  
   `GET /face-search/{search_id}` every 3–5 seconds:

   ```bash
   curl https://gateway.nuwa.world/api/v1/face-search/abc123 \
     -H "X-API-Key: $NUWA_API_KEY"
   ```

   - While processing: `status: "processing"`, empty `results`
   - When complete: `status: "completed"` plus an array of `{ index, score, url }`
   - Typical latency: 15–30 seconds
   - Results expire ~2 hours after completion

### Deep Research

Single synchronous call (cost: 20 credits).

```bash
curl -X POST https://gateway.nuwa.world/api/v1/deep-research \
  -H "X-API-Key: $NUWA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "0xajc on X"}'
```

- Response includes a `summary`, a `facts` list, and `sources` with titles and...