---
name: sukidata
description: Use Sukidata for structured Google search results, public Twitter timelines, and AI image generation or editing. Guides agents using Sukidata tools during a task or integrating its APIs into an application.
---

# Sukidata

Sukidata provides structured web data and AI image tools. Use it to find sources,
follow public accounts, create images from a prompt, or edit images with references
and masks. It is available through MCP and the HTTPS API.

## Choose a service

| Task | MCP tool | HTTP endpoint |
| --- | --- | --- |
| Find web sources, news, products or existing images | `google_search` | `POST /v1/serp` |
| Read a public Twitter account's posts | `twitter_user_timeline` | `POST /v1/twitter` |
| Create images from text, optionally with references | `generate_image` | `POST /v1/images/generations/async` |
| Change an existing image, optionally with a mask | `edit_image` | `POST /v1/images/edits/async` |
| Continue a pending search or timeline request | `get_result` | `GET /v1/serp/{search_id}` or `GET /v1/twitter/{search_id}` |
| Wait for or retrieve an image task | `get_image_task` | `GET /v1/images/tasks/{task_id}` |

Searching for existing images and generating new images are different tasks:
use Google image search for discovery and image generation for creating artwork.
Search results are not full-page extraction; use the returned source URLs when
the task requires visiting or citing an original page.

## Choose an integration

### Use tools in the current session

Use an already-connected Sukidata MCP server when available. Discover its tools
and use their input schemas; MCP argument names differ from HTTP request fields.
For example, Google MCP uses `query`, while the HTTP API uses `q`.

To connect, add a remote MCP server with these values:

- Name: `sukidata`
- Transport: Streamable HTTP
- URL: `https://mcp.sukidata.com/mcp`
- Header: `Authorization: Bearer <your Sukidata API key>`

Use the current client's supported configuration format. The Overview page at
https://app.sukidata.com/ provides an agent setup prompt and a ready-to-copy
configuration. Verify setup by connecting and listing tools; no paid execution
is needed just to check the connection.

### Call the API from an app or script

Base URL: `https://api.sukidata.com`. Read `SUKIDATA_API_KEY` from the runtime
environment and send it in the `Authorization: Bearer` header. Keep credentials
in server-side configuration, not browser bundles, skill files, request URLs or logs.

Inspect an existing project's API client and secret handling before integrating.
Use the [API reference](https://docs.sukidata.com/api-reference/) for request and
response schemas rather than translating MCP arguments literally.

If credentials are missing, ask the user to connect MCP or set the environment
variable. Users can create or manage keys at https://app.sukidata.com/api-keys.
Do not create an account, key or paid request just because this guide was loaded.

## Google Search

Use `google_search` for one page of structured Google results. It supports
`web`, `images`, `local`, `videos`, `news`, `shopping` and `patents` search types.
Choose the market with `country_code`, `language_code`, `google_domain` and,
when needed, `location`. Standard Google query operators such as `site:` work.
Use `start` for the result offset; keep the query and market consistent when paging.

Example MCP arguments:

```json
{
  "query": "coffee roasters in Seattle",
  "country_code": "us",
  "language_code": "en",
  "search_type": "web"
}
```

Keep `fresh` false unless the task needs a new fetch instead of a reusable result.
When a result is pending, use `get_result` with `product: "serp"` and the returned
`search_id`. Present source links with the findings.

[Google Search parameters and responses](https://docs.sukidata.com/api-reference/endpoint/google-search/)

## Public Twitter timelines

Use `twitter_user_timeline` to read one public account's posts. Supply exactly
one of `username` (with or without `@`) or numeric `user_id`. `max_results`
defaults to 20 and accepts 1–100. Continue with the returned `next_cursor` in
`cursor`, unchanged. Stop when no next cursor is returned or the task has enough posts.

For a pending request, use `get_result` with `product: "twitter"` and the returned
`search_id`. HTTP responses expose that ID as `search_metadata.id`; retrieve it
at `/v1/twitter/{search_id}`. Google HTTP requests follow the same pattern under
`/v1/serp/{search_id}`.

[Twitter parameters and responses](https://docs.sukidata.com/api-reference/endpoint/twitter-user-timeline/)

## Generate and edit images

Use `generate_image` for new artwork and `edit_image` to modify existing images.
Both require `model`, `prompt` and an `idempotency_key`. Available models include
`gpt-image-2.5` and `gpt-image-2`; direct API clients can discover models with
`GET /v1/models`.

Both models accept 1–4 output images with `n` (default 1). Quality accepts
`auto`, `low`, `medium` or `high`. Output formats are `png`, `jpeg` and `webp`.
Use PNG or WebP for transparent output. Omitted settings use model defaults.
Set `size` to `auto` or `WIDTHxHEIGHT`; consult the image reference for valid
dimensions and the [billing guide](https://docs.sukidata.com/billing/) for 1K presets.

Example MCP arguments (replace the example idempotency key for a new creation):

```json
{
  "model": "gpt-image-2.5",
  "prompt": "A blue ceramic coffee cup on a clean white background",
  "idempotency_key": "coffee-cup-example-1",
  "size": "1254x1254",
  "quality": "high",
  "n": 1
}
```

### References and local images

`edit_image` requires `images`; `generate_image` can also take references.
Supply 1–16 PNG, JPEG or WebP references as public HTTPS URLs or Base64 data URLs.
Each file can be up to 20 MiB, with 32 MiB total including the mask.
Reference count and output count are separate controls.

With remote MCP, read the user-selected local files and send their bytes as
`data:image/png;base64,...`, `data:image/jpeg;base64,...` or
`data:image/webp;base64,...`. Do not send a filesystem path to the remote server.
An already-configured local Sukidata stdio server can read explicit file paths.
Preserve source bytes; do not resize or re-encode references merely to upload them.

An optional `mask` must be a PNG matching the first reference image's dimensions.
Transparent areas mark where to edit. Keep reference order and include the same
mask when retrying an interrupted submission. A previous output URL can be reused
as a reference while it remains available.

### Follow the task, not the submission

Image generation commonly takes 30 seconds to two minutes. Submit once, retain
the returned `task_id`, then call `get_image_task` with `wait_seconds: 20`.
If still `generating`, follow `poll_after_seconds` and retrieve the same task again.
Use `wait_seconds: 0` for a single status check. `completed` and `failed` are
terminal MCP states; the HTTP API also exposes `queued`, `processing` and `unknown`
for tasks whose result is not yet confirmed.

Each intended creation needs a unique MCP `idempotency_key`, or an
`Idempotency-Key` header for HTTP. Retry an interrupted submission with the same
key and unchanged arguments/files. If a task ID is known, retrieve it instead
of submitting again. A query error or expired wait does not mean generation
failed, and ending a wait does not cancel the task or its charge. If the user
stops waiting, give them the task ID so they can retrieve it later.

Completed MCP results include public image URLs and, when available, inline
image content. Show the images and their download links. Save important outputs
before `url_expires_at`; anyone with a public output URL can open it.
For HTTP integrations, use the async endpoints in the table and poll
`GET /v1/images/tasks/{task_id}`. Existing tasks are also available in the App.

[Image parameters, masks and task responses](https://docs.sukidata.com/api-reference/endpoint/images/)

## Billing and recovery

Web Data uses Workspace Credits; image generation and editing use AI Balance
in USD. Each output image is billable. Retrieving an existing result does not
create another execution. Make only the requests needed for the user's task.

- Authentication or permission error: check the configured key and its access;
  ask the user to resolve missing access rather than trying other credentials.
- Insufficient balance: stop new submissions and tell the user which balance
  needs attention.
- Invalid input: use the returned error and published schema to correct the
  request; do not repeatedly send the same invalid payload.
- Rate limit: follow the returned retry guidance. For accepted image tasks,
  keep retrieving the same task instead of generating another image.

[MCP tools and connection guide](https://docs.sukidata.com/mcp/)