Geelark OpenAPI – Cloud Phone Creation

Endpoint

POST

https://openapi.geelark.com/open/v1/phone/addNew

Creates one or more cloud phones (Android virtual devices) with isolated profiles.

Plan Constraints

• Basic plan: supports creation of only one cloud phone at a time
• Pro plan: supports batch creation (up to 100 per request)
• Batch creation may be further limited by:
• 
  
• plan quota
• daily creation limits

Dependencies

• Supported brand + model combinations must be fetched via the cloud phone brand list API before use.
• Proxy priority order:
• 
  
• proxyInformation
• dynamicProxy
• At least one proxy source must be provided if proxying is required.

Request Parameters (Top-Level)

mobileType

 (string, required)

Android OS version of the cloud phone.

Supported values:

• Android 9
• Android 10
• Android 11
• Android 12
• Android 13
• Android 14
• Android 15

Example:

Android 10

chargeMode

 (integer, optional)

Billing mode.

Values:

• 0 → on-demand (default)
• 1 → monthly

Example:

0

region

 (string, optional)

Datacenter region where the cloud phone is hosted.

Values:

• cn
• sgp

Default:

cn

data

 (array[EnvRowApi], required)

Array of cloud phone environment definitions.

Constraints:

• Maximum: 100 items per request

EnvRowApi (Cloud Phone Environment)

profileName

 (string, required)

Human-readable cloud phone name.

Example:

myPhone

proxyInformation

 (string, optional)

Proxy connection string.

Supported types:

• http
• https
• socks5

Example:

socks5://user:pass@ip:port

refreshUrl

 (string, optional)

URL used to refresh proxy IP.

proxyNumber

 (integer, optional)

Serial number of a previously added proxy.

dynamicProxy

 (string, optional)

Reference to a saved dynamic proxy provider.

Supported values:

• IPIDEA
• IPHTML
• kookeey
• Luminati (BrightData)
• rolaip
• Proxyma
• DECODO
• NodeMaven
• IPIDEAMobile
• kookeeyMobile

dynamicProxyLocation

 (string, optional)

Country code for dynamic proxy location.

Required if dynamicProxy is set.

Example:

us

mobileLanguage

 (string, optional)

Language setting of the cloud phone.

Values:

• baseOnIP → derived from proxy
• default → English (default)

profileGroup

 (string, optional)

Profile group name.

• Created automatically if it does not exist.

profileTags

 (array[string], optional)

Profile tags.

• Tags are created automatically if they do not exist.

profileNote

 (string, optional)

Free-form remark.

surfaceBrandName

 (string, optional)

Device brand.

• Must match the selected Android version.
• Must be used together with surfaceModelName.

Example:

samsung

surfaceModelName

 (string, optional)

Device model.

• Must match the selected Android version.

Example:

Galaxy S23

netType

 (integer, optional)

Network type.

Values:

• 0 → Wi-Fi
• 1 → Mobile network

Notes:

• Only supported on Android 12 / 13 / 15
• Default: Mobile network

phoneNumber

 (string, optional)

Phone number assigned to the cloud phone.

• Automatically generated if omitted.

Example:

+66817806147

Request Example

{
  "mobileType": "Android 12",
  "chargeMode": 0,
  "data": [
    {
      "profileName": "myPhone",
      "proxyInformation": "socks5://AD00xx004:3000xxx0002@100.200.200.100:30000",
      "mobileLanguage": "default",
      "profileGroup": "myGroup",
      "profileTags": ["myTag"],
      "profileNote": "remark"
    }
  ]
}

Response Structure

Top-Level Response

{
  "traceId": "string",
  "code": 0,
  "msg": "success",
  "data": { ... }
}

• code = 0 indicates success

Response Data

Field

Type

Description

totalAmount

integer

Total requested cloud phones

successAmount

integer

Successfully created

failAmount

integer

Failed creations

details

array

Per-phone creation results

details[] Object

Field

Type

Description

index

integer

Creation index

code

integer

Result code (0 = success)

msg

string

Result message

id

string

Cloud phone ID

profileName

string

Cloud phone name

envSerialNo

string

Cloud phone serial number

equipmentInfo

object

Device hardware metadata

equipmentInfo Object

Field

Type

Description

countryName

string

Country

phoneNumber

string

Phone number

enableSim

integer

SIM enabled (0/1)

imei

string

IMEI

osVersion

string

Android version

wifiBssid

string

Wi-Fi BSSID

mac

string

Wi-Fi MAC address

bluetoothMac

string

Bluetooth MAC

timeZone

string

Time zone

deviceBrand

string

Device brand

deviceModel

string

Device model

Error Codes

Code

Description

44001

Batch creation not allowed (upgrade to Pro plan)

44002

Cloud phone creation limit reached for plan

44004

Daily cloud phone creation limit reached

50000

Unknown error

Notes for LLM Usage

• Batch size hard limit: 100 environments
• Brand/model must be validated externally
• Device creation is constrained by plan + daily quotas
• Cloud phone identity includes hardware-level identifiers (IMEI, MACs)

If you want, next I can:

• normalize this into OpenAPI YAML
• create a TypeScript interface
• or generate prompt rules so an LLM uses this API safely and correctly inside Context7