Getting Started

Build with SeeAPI using one workflow: choose a model, submit a generation, and retrieve its finished assets. This guide covers your first request and the essentials to check before production.

1. Explore models and API capabilities

Browse Image Models and Video Models in the Docs sidebar, then open the model and Endpoint guide for the capability you need. Each guide describes its supported inputs, Provider options, limits, pricing, and request examples.

A model identifies what to run; an Endpoint identifies the task, such as text-to-image or image-to-video.

Available inputs, limits, and output options can differ by Provider. Use the documentation for the Provider you select.

Use the model and Endpoint IDs documented in the selected guide. Actual calls remain subject to your API key permissions; if access is denied, check your account access or contact support.

2. Check pricing and credits

Use API Pricing for API rates. Charges depend on the selected model, Provider, and request settings; do not assume the web generator and API have the same price.

You can check your balance with GET /v1/credits. An insufficient balance returns HTTP 402. Review the current price before sending a real generation request.

3. Create and protect your API key

Create a key in API Keys and store the full value securely when it is shown. See Authentication for the complete setup.

⚠️ Keep your API key on your server or in a secrets manager. Never place it in browser code, mobile app bundles, public repositories, URLs, or logs.

For this environment, configure your server-side shell with the following API base URL and your own key:

export SEEAPI_API_BASE_URL='https://api.seeapi.com'
export SEEAPI_API_KEY='YOUR_API_KEY'

Send Authorization: Bearer <API_KEY> with authenticated requests. JSON requests also need Content-Type: application/json. Use the base URL provided for your target environment, not the Docs website URL.

4. Create your first generation

Choose a documented model and Endpoint

Copy the model and Endpoint IDs from the selected model documentation. For example:

{
  "model": "z-image-turbo",
  "endpoint": "text-to-image"
}

The example below uses z-image-turbo with text-to-image. Review its model guide before submitting. To use a different model, copy its documented IDs and adapt input to that Endpoint's requirements.

Submit a task

Choose a new idempotency key for this task and keep it with the request. Replace the example key before starting a different generation:

export SEEAPI_IDEMPOTENCY_KEY='quickstart-001'

curl -X POST "$SEEAPI_API_BASE_URL/v1/generations" \
  -H "Authorization: Bearer $SEEAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $SEEAPI_IDEMPOTENCY_KEY" \
  -d '{
    "model": "z-image-turbo",
    "endpoint": "text-to-image",
    "input": {
      "prompt": "A cinematic city at night",
      "aspect_ratio": "1:1"
    }
  }'

This example omits provider to use the Endpoint default. To select one explicitly, use a public Provider ID listed in that model's Endpoint documentation and follow that Provider's input requirements.

HTTP 202 means the task was accepted—not that generation has finished. Save the complete generation.id from the response; you will need it to retrieve the result.

5. Wait for completion and retrieve results

Replace task_xxx with the exact ID returned by your request:

export SEEAPI_TASK_ID='task_xxx'

curl "$SEEAPI_API_BASE_URL/v1/generations/$SEEAPI_TASK_ID" \
  -H "Authorization: Bearer $SEEAPI_API_KEY"

processing: the task is still running. Poll again with an increasing delay.

succeeded: read the generated files from generation.result.assets.

failed, canceled, refunded, or expired: stop polling and inspect the task details.

The Get Task Details reference explains the response. In task-detail responses, consumed_credits is an estimate while processing and actual usage after the task reaches a terminal state.

6. Use webhooks and safe retries

For production workflows, you can provide an absolute HTTPS callback_url at the top level of your generation request to receive terminal task updates. Keep polling available as a recovery path.

Verify webhook signatures with your Webhook Signing Secret. It is separate from your API key.

Handle duplicate webhook deliveries safely before triggering downstream actions.

If a creation request times out, retry with the same Idempotency-Key and exactly the same request body. Do not generate a new key just because the response was lost.

An idempotent replay returns HTTP 200. Reusing a key with a different request body returns HTTP 409.

Keep an idempotency key at most 255 characters long. See Create a Generation for request and response details.

7. Validate inputs and handle errors

Check model- and Provider-specific requirements before submitting: text length, supported formats, file size, dimensions, duration, reference count, and conditions between parameters. There is no single set of media limits for every model.

400: fix the JSON or invalid parameters before retrying.

401 / 403: check your credentials and access permissions.

402: check your credit balance.

404: check the model and Endpoint IDs against their documentation, or verify the exact task or asset ID and target environment.

429: reduce request frequency and follow Retry-After. Use backoff instead of sending immediate retries.

Retry network failures and recoverable server errors with backoff. For task creation, keep the original idempotency key and request body. A request error and a task that later fails are different cases; inspect the task state before deciding what to do next.

8. Inspect usage and store your results

Use API Tasks to investigate individual requests and API Usage to monitor activity and credit consumption. Keep the task ID when reporting a problem.

Task logs are retained for 60 days. Export or back up important records before they expire if you need to keep them longer.

For asset metadata, request:

curl "$SEEAPI_API_BASE_URL/v1/generations/$SEEAPI_TASK_ID/assets" \
  -H "Authorization: Bearer $SEEAPI_API_KEY"

Generated assets currently have no automatic expiration period. Platform storage is not a substitute for your own backups; keep copies of business-critical assets.

9. Next steps and support

Authentication — configure credentials and secure your integration.

Model guides — choose a model from Image Models or Video Models in the Docs sidebar and review its Endpoint and Provider requirements.

Create a Generation — review the complete request contract.

Get Task Details — understand task status and results.

API Updates — review changes that may affect your integration.

Need help? Contact [email protected] with the model, Endpoint, task ID, time of the issue, and a redacted error message. Never include your API key or Webhook Signing Secret.