API Documentation

Get Started

Generate API Key

Before using the API, you need to create an API key. Go to the API Keys page to generate your key.

API Endpoints

Base URL:https://api.dh3.app

Endpoint	Method	Description
`/api/v1/task/create`	POST	Create / Submit a generation task
`/api/v1/task/get`	GET	Query task status and result

Rate Limit: /api/v1/task/create has a default QPS of 3. Contact us if you need a higher rate limit.

Nano Banana Pro

Create Task

POST/api/v1/task/create

Submit a new AI image generation task

Request Headers

Header	Value
`Authorization`	Bearer YOUR_API_KEY
`Content-Type`	application/json

Request Parameters

Field	Type	Required	Description
`model`	string	Yes	Model name, e.g. "nano-banana-pro"
`nano_banana_pro_input`	object	Yes	Input parameters for nano-banana-pro model
`callback_url`	string	No	URL to receive task result events. POST request will be sent when task completes (success/fail).

`nano_banana_pro_input` Parameters

Field	Type	Required	Description
`prompt`	string	Yes	Text prompt, 3-20000 characters
`image_urls`	string[]	No	Reference image URLs (0-8 images, max 30MB each)
`aspect_ratio`	string	No	1:1 \| 2:3 \| 3:2 \| 3:4 \| 4:3 \| 4:5 \| 5:4 \| 9:16 \| 16:9 \| 21:9 \| auto (default: 1:1)
`resolution`	string	No	1K \| 2K \| 4K (default: 1K)
`output_format`	string	No	png \| jpg (default: png)

Request Body Example

{
  "model": "nano-banana-pro",
  "nano_banana_pro_input": {
    "prompt": "chinese girl with golden yellow hair is dancing, wearing black hot bikini suit, 4k",
    "image_urls": [
      "https://tempfile.aiquickdraw.com/workers/nano/image_1769080764854_k0gub3.jpg"
    ],
    "aspect_ratio": "21:9",
    "resolution": "1K"
  },
  "callback_url": "https://your-domain.ai/api/callback"
}

Response Fields

Field	Type	Description
`code`	int	200 = success, other values indicate failure
`message`	string	Response message
`task_id`	string	Unique task identifier for status polling

Response Example

{
  "code": 200,
  "message": "ok",
  "task_id": "76808142f56692acea353e2d1dc90e9e"
}

Playground

API Key

Loading keys...

Prompt

Aspect Ratio

Resolution

1import requests
2import json
3
4url = "https://api.dh3.app/api/v1/task/create"
5headers = {
6    "Authorization": "Bearer YOUR_API_KEY",
7    "Content-Type": "application/json"
8}
9data = {
10    "model": "nano-banana-pro",
11    "nano_banana_pro_input": {
12        "prompt": "A beautiful sunset over mountains, 4k, photorealistic",
13        "aspect_ratio": "1:1",
14        "resolution": "1K"
15    }
16}
17
18response = requests.post(url, headers=headers, json=data)
19result = response.json()
20print(json.dumps(result, indent=2))

Webhook Callback

Receive task completion notifications via webhook

Callback Request Parameters

Field	Type	Description
`code`	int	200 = success
`message`	string	Response message
`nano_banana_pro_output`	object	Output object for nano-banana-pro model

`nano_banana_pro_output` Fields

Field	Type	Description
`task_id`	string	Task identifier
`status`	string	Task status: success \| fail
`images`	array	Array of generated images (present when status is success)
`err_msg`	string	Error message (present when status is fail)

ImageFile Object

Field	Type	Description
`url`	string	URL to access the generated image
`content_type`	string	MIME type, e.g. image/png
`file_name`	string	Image file name
`file_size`	string	File size in bytes
`width`	string	Image width in pixels
`height`	string	Image height in pixels

Callback Request Example

Task Success

{
  "code": 200,
  "message": "Ok",
  "nano_banana_pro_output": {
    "task_id": "76808142f56692acea353e2d1dc90e9e",
    "status": "success",
    "images": [
      {
        "url": "https://tempfile.aiquickdraw.com/workers/nano/result.png",
        "content_type": "image/png",
        "file_name": "result.png",
        "file_size": "2456789",
        "width": "1024",
        "height": "1024"
      }
    ]
  }
}

Task Failed

{
  "code": 200,
  "message": "Ok",
  "nano_banana_pro_output": {
    "task_id": "76808142f56692acea353e2d1dc90e9e",
    "status": "fail",
    "err_msg": "Upstream model error"
  }
}

Callback Response Requirements

After receiving the callback request, the integrating service should return HTTP 200 status code upon successful processing.

Return HTTP 200

Indicates successful receipt and processing of callback content. No retry will be attempted.

Return non-200 status code

(e.g., 4xx/5xx), or server fails to respond within a reasonable time: treated as callback failure, will trigger retries.

Retry Mechanism

If the integrating service does not return HTTP 200, the system will automatically retry.

Retry Strategy

Maximum 3 retries (excluding the initial request)
If all 3 retries fail, callbacks will stop and no further attempts will be made

Notes

Callback request idempotency is the responsibility of the integrating service (e.g., check if task_id has been processed)

For complex business logic, it's recommended to return 200 quickly first, then process asynchronously to avoid duplicate callbacks due to timeout

Get Result

GET/api/v1/task/get

Get task status and result by task_id

Request Headers

Header	Value
`Authorization`	Bearer YOUR_API_KEY
`Content-Type`	application/json

Request Parameters

Field	Type	Required	Description
`task_id`	string	Yes	Task ID returned from create endpoint

Request Body Example

{
  "task_id": "76808142f56692acea353e2d1dc90e9e"
}

Response Fields

Field	Type	Description
`code`	int	200 = success, other values indicate failure
`message`	string	Response message
`nano_banana_pro_output`	object	Output object for nano-banana-pro model

`nano_banana_pro_output` Fields

Field	Type	Description
`task_id`	string	Task identifier
`status`	string	Task status: queuing \| processing \| success \| fail
`images`	array	Array of generated images (present when status is success)
`err_msg`	string	Error message (present when status is fail)

ImageFile Object

Field	Type	Description
`url`	string	URL to access the generated image
`content_type`	string	MIME type, e.g. image/png
`file_name`	string	Image file name
`file_size`	string	File size in bytes
`width`	string	Image width in pixels
`height`	string	Image height in pixels

Response Example

{
  "code": 200,
  "message": "Ok",
  "nano_banana_pro_output": {
    "task_id": "76808142f56692acea353e2d1dc90e9e",
    "status": "success",
    "images": [
      {
        "url": "https://tempfile.aiquickdraw.com/workers/nano/result.png",
        "content_type": "image/png",
        "file_name": "result.png",
        "file_size": "2456789",
        "width": "1024",
        "height": "1024"
      }
    ]
  }
}

Playground

API Key

Loading keys...

Task ID

1import requests
2import json
3
4url = "https://api.dh3.app/api/v1/task/get"
5headers = {
6    "Authorization": "Bearer YOUR_API_KEY",
7    "Content-Type": "application/json"
8}
9params = {"task_id": "YOUR_TASK_ID"}
10
11response = requests.get(url, headers=headers, params=params)
12result = response.json()
13print(json.dumps(result, indent=2))

Get Started

Generate API Key

API Endpoints

Nano Banana Pro

Create Task

Request Headers

Request Parameters

nano_banana_pro_input Parameters

Request Body Example

Response Fields

Response Example

Playground

Webhook Callback

Callback Request Parameters

nano_banana_pro_output Fields

ImageFile Object

Callback Request Example

Callback Response Requirements

Retry Mechanism

Retry Strategy

Notes

Get Result

Request Headers

Request Parameters

Request Body Example

Response Fields

nano_banana_pro_output Fields

ImageFile Object

Response Example

Playground

`nano_banana_pro_input` Parameters

`nano_banana_pro_output` Fields

`nano_banana_pro_output` Fields